chore: Added linting to error on relative imports and using path aliases

.changeset/selfish-oranges-cheer.md

@@ -0,0 +1,9 @@
+---
+"@hyperdx/common-utils": patch
+"@hyperdx/hdx-eval": patch
+"@hyperdx/api": patch
+"@hyperdx/app": patch
+"@hyperdx/cli": patch
+---
+
+Removing relative imports and using path aliases

packages/api/eslint.config.mjs

@@ -74,6 +74,18 @@ export default [
       'prettier/prettier': 'error',
       'simple-import-sort/imports': 'error',
       'simple-import-sort/exports': 'error',
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              regex: '^\\.\\.(/|$)',
+              message:
+                'Use the @/ path alias instead of parent-relative imports (../).',
+            },
+          ],
+        },
+      ],
     },
     languageOptions: {
       parser: tseslint.parser,

packages/api/scripts/generate-api-docs.ts

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import swaggerJsdoc from 'swagger-jsdoc';
 
+// eslint-disable-next-line no-restricted-imports -- run via ts-node without tsconfig-paths, so @/ does not resolve here
 import { swaggerOptions } from '../src/utils/swagger';
 
 const specs = swaggerJsdoc(swaggerOptions);

packages/api/src/mcp/__tests__/alerts.test.ts

@@ -8,14 +8,14 @@ import {
   getLoggedInAgent,
   getServer,
 } from '@/fixtures';
+import { McpContext } from '@/mcp/tools/types';
 import Alert, { AlertState } from '@/models/alert';
 import Connection from '@/models/connection';
 import Dashboard from '@/models/dashboard';
 import { SavedSearch } from '@/models/savedSearch';
 import { Source } from '@/models/source';
 import Webhook, { WebhookService } from '@/models/webhook';
 
-import { McpContext } from '../tools/types';
 import { callTool, createTestClient, getFirstText } from './mcpTestUtils';
 
 describe('MCP Alert Tools', () => {

packages/api/src/mcp/__tests__/dashboards/deleteDashboard.test.ts

@@ -1,6 +1,6 @@
+import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils';
 import Dashboard from '@/models/dashboard';
 
-import { callTool, getFirstText } from '../mcpTestUtils';
 import { setupDashboardTests } from './setup';
 
 describe('MCP Dashboard Tools - clickstack_delete_dashboard', () => {

packages/api/src/mcp/__tests__/dashboards/getDashboard.test.ts

@@ -1,6 +1,6 @@
+import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils';
 import Dashboard from '@/models/dashboard';
 
-import { callTool, getFirstText } from '../mcpTestUtils';
 import { setupDashboardTests } from './setup';
 
 describe('MCP Dashboard Tools - clickstack_get_dashboard', () => {

packages/api/src/mcp/__tests__/dashboards/getDashboardTile.test.ts

@@ -1,6 +1,6 @@
+import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils';
 import Dashboard from '@/models/dashboard';
 
-import { callTool, getFirstText } from '../mcpTestUtils';
 import { setupDashboardTests } from './setup';
 
 describe('MCP Dashboard Tools - clickstack_get_dashboard_tile', () => {

packages/api/src/mcp/__tests__/dashboards/patchDashboard.test.ts

@@ -1,7 +1,7 @@
+import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils';
 import Dashboard from '@/models/dashboard';
 import type { ExternalDashboardTileWithId } from '@/utils/zod';
 
-import { callTool, getFirstText } from '../mcpTestUtils';
 import { setupDashboardTests } from './setup';
 
 describe('MCP Dashboard Tools - clickstack_patch_dashboard', () => {

packages/api/src/mcp/__tests__/dashboards/prompts.test.ts

@@ -2,8 +2,8 @@ import {
   buildCreateDashboardPrompt,
   buildDashboardExamplesPrompt,
   buildQueryGuidePrompt,
-} from '../../prompts/dashboards/content';
-import { buildSourceSummary } from '../../prompts/dashboards/helpers';
+} from '@/mcp/prompts/dashboards/content';
+import { buildSourceSummary } from '@/mcp/prompts/dashboards/helpers';
 
 describe('MCP Dashboard Prompts', () => {
   describe('buildQueryGuidePrompt', () => {

packages/api/src/mcp/__tests__/dashboards/queryTile.test.ts

@@ -1,4 +1,5 @@
-import { callTool, getFirstText } from '../mcpTestUtils';
+import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils';
+
 import { setupDashboardTests } from './setup';
 
 describe('MCP Dashboard Tools - clickstack_query_tile', () => {

packages/api/src/mcp/__tests__/dashboards/saveDashboard.test.ts

@@ -2,11 +2,11 @@ import { MetricsDataType, SourceKind } from '@hyperdx/common-utils/dist/types';
 import mongoose from 'mongoose';
 
 import { DEFAULT_DATABASE } from '@/fixtures';
+import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils';
 import Dashboard from '@/models/dashboard';
 import { Source } from '@/models/source';
 import type { ExternalDashboardTileWithId } from '@/utils/zod';
 
-import { callTool, getFirstText } from '../mcpTestUtils';
 import { setupDashboardTests } from './setup';
 
 describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {

packages/api/src/mcp/__tests__/dashboards/searchDashboards.test.ts

@@ -1,8 +1,8 @@
 import mongoose from 'mongoose';
 
+import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils';
 import Dashboard from '@/models/dashboard';
 
-import { callTool, getFirstText } from '../mcpTestUtils';
 import { setupDashboardTests } from './setup';
 
 describe('MCP Dashboard Tools - clickstack_search_dashboards', () => {

packages/api/src/mcp/__tests__/dashboards/setup.ts

@@ -8,12 +8,11 @@ import {
   getLoggedInAgent,
   getServer,
 } from '@/fixtures';
+import { createTestClient } from '@/mcp/__tests__/mcpTestUtils';
+import { McpContext } from '@/mcp/tools/types';
 import Connection from '@/models/connection';
 import { Source } from '@/models/source';
 
-import { McpContext } from '../../tools/types';
-import { createTestClient } from '../mcpTestUtils';
-
 /**
  * Shared setup/teardown for all dashboard MCP tool tests.
  *

packages/api/src/mcp/__tests__/dashboards/validation.test.ts

@@ -1,12 +1,11 @@
 import mongoose from 'mongoose';
 
-import type { ExternalDashboardTileWithId } from '@/utils/zod';
-
 import {
   getRawSqlMissingSourceError,
   getRawSqlTileMacroWarnings,
   getRawSqlTilesMissingRequiredSource,
-} from '../../tools/dashboards/validation';
+} from '@/mcp/tools/dashboards/validation';
+import type { ExternalDashboardTileWithId } from '@/utils/zod';
 
 const connectionId = new mongoose.Types.ObjectId().toString();
 const sourceId = new mongoose.Types.ObjectId().toString();

packages/api/src/mcp/__tests__/deltasTool.test.ts

@@ -9,10 +9,10 @@ import {
   getLoggedInAgent,
   getServer,
 } from '@/fixtures';
+import { McpContext } from '@/mcp/tools/types';
 import Connection from '@/models/connection';
 import { Source } from '@/models/source';
 
-import { McpContext } from '../tools/types';
 import { callTool, createTestClient, getFirstText } from './mcpTestUtils';
 
 describe('MCP Event Deltas Tool', () => {

packages/api/src/mcp/__tests__/mcpTestUtils.ts

@@ -5,8 +5,8 @@ import {
   CallToolResultSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 
-import { createServer } from '../mcpServer';
-import { McpContext } from '../tools/types';
+import { createServer } from '@/mcp/mcpServer';
+import { McpContext } from '@/mcp/tools/types';
 
 /**
  * Connect an MCP server to an in-process Client via InMemoryTransport and

packages/api/src/mcp/__tests__/query.test.ts

@@ -10,8 +10,8 @@ import {
   errorHint,
   mergeWhereIntoSelectItems,
   parseTimeRange,
-} from '../tools/query/helpers';
-import { resolveOrderBy } from '../tools/query/table';
+} from '@/mcp/tools/query/helpers';
+import { resolveOrderBy } from '@/mcp/tools/query/table';
 
 describe('parseTimeRange', () => {
   it('should return default range (last 15 minutes) when no arguments provided', () => {

packages/api/src/mcp/__tests__/queryTool.test.ts

@@ -11,10 +11,10 @@ import {
   getLoggedInAgent,
   getServer,
 } from '@/fixtures';
+import { McpContext } from '@/mcp/tools/types';
 import Connection from '@/models/connection';
 import { Source, type SourceDocument } from '@/models/source';
 
-import { McpContext } from '../tools/types';
 import { callTool, createTestClient, getFirstText } from './mcpTestUtils';
 
 describe('MCP Query Tools', () => {

packages/api/src/mcp/__tests__/savedSearches.test.ts

@@ -8,11 +8,11 @@ import {
   getLoggedInAgent,
   getServer,
 } from '@/fixtures';
+import { McpContext } from '@/mcp/tools/types';
 import Connection from '@/models/connection';
 import { SavedSearch } from '@/models/savedSearch';
 import { Source } from '@/models/source';
 
-import { McpContext } from '../tools/types';
 import { callTool, createTestClient, getFirstText } from './mcpTestUtils';
 
 describe('MCP Saved Search Tools', () => {

packages/api/src/mcp/__tests__/sources.test.ts

@@ -9,11 +9,11 @@ import {
   getLoggedInAgent,
   getServer,
 } from '@/fixtures';
+import { McpContext } from '@/mcp/tools/types';
 import Connection from '@/models/connection';
 import { Source } from '@/models/source';
 import Team from '@/models/team';
 
-import { McpContext } from '../tools/types';
 import { callTool, createTestClient, getFirstText } from './mcpTestUtils';
 
 describe('MCP Source Tools', () => {

packages/api/src/mcp/__tests__/trace.test.ts

@@ -10,10 +10,10 @@ import {
   getLoggedInAgent,
   getServer,
 } from '@/fixtures';
+import { McpContext } from '@/mcp/tools/types';
 import Connection from '@/models/connection';
 import { Source, type SourceDocument } from '@/models/source';
 
-import { McpContext } from '../tools/types';
 import { callTool, createTestClient, getFirstText } from './mcpTestUtils';
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────

packages/api/src/mcp/__tests__/tracing.test.ts

@@ -42,7 +42,7 @@ jest.mock('@/utils/logger', () => ({
   },
 }));
 
-import { withToolTracing } from '../utils/tracing';
+import { withToolTracing } from '@/mcp/utils/tracing';
 
 describe('withToolTracing', () => {
   const context = { teamId: 'team-123', userId: 'user-456' };

packages/api/src/mcp/app.ts

@@ -2,9 +2,10 @@ import { setTraceAttributes } from '@hyperdx/node-opentelemetry';
 import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
-import { validateUserAccessKey } from '../middleware/auth';
-import logger from '../utils/logger';
-import rateLimiter, { rateLimiterKeyGenerator } from '../utils/rateLimiter';
+import { validateUserAccessKey } from '@/middleware/auth';
+import logger from '@/utils/logger';
+import rateLimiter, { rateLimiterKeyGenerator } from '@/utils/rateLimiter';
+
 import { createServer } from './mcpServer';
 import { McpContext } from './tools/types';
 

packages/api/src/mcp/prompts/dashboards/index.ts

@@ -2,9 +2,9 @@ import { z } from 'zod';
 
 import { getConnectionsByTeam } from '@/controllers/connection';
 import { getSources } from '@/controllers/sources';
+import type { PromptDefinition } from '@/mcp/tools/types';
 import logger from '@/utils/logger';
 
-import type { PromptDefinition } from '../../tools/types';
 import {
   buildCreateDashboardPrompt,
   buildDashboardExamplesPrompt,

packages/api/src/mcp/tools/alerts/getAlert.ts

@@ -7,15 +7,14 @@ import { z } from 'zod';
 import * as config from '@/config';
 import { getRecentAlertHistories } from '@/controllers/alertHistory';
 import { getAlertById } from '@/controllers/alerts';
+import type { McpContext } from '@/mcp/tools/types';
+import { validateObjectId } from '@/mcp/utils/errors';
+import { withToolTracing } from '@/mcp/utils/tracing';
 import Alert from '@/models/alert';
 import type { IDashboard } from '@/models/dashboard';
 import type { ISavedSearch } from '@/models/savedSearch';
 import { translateAlertDocumentToExternalAlert } from '@/utils/externalApi';
 
-import { validateObjectId } from '../../utils/errors';
-import { withToolTracing } from '../../utils/tracing';
-import type { McpContext } from '../types';
-
 function deriveAlertName(alert: {
   name?: string | null;
   tileId?: string;

packages/api/src/mcp/tools/alerts/getWebhook.ts

@@ -1,11 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 
+import type { McpContext } from '@/mcp/tools/types';
+import { withToolTracing } from '@/mcp/utils/tracing';
 import Webhook from '@/models/webhook';
 
-import { withToolTracing } from '../../utils/tracing';
-import type { McpContext } from '../types';
-
 export function registerGetWebhook(
   server: McpServer,
   context: McpContext,

packages/api/src/mcp/tools/alerts/index.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
-import type { McpContext, ToolDefinition } from '../types';
+import type { McpContext, ToolDefinition } from '@/mcp/tools/types';
+
 import { registerGetAlert } from './getAlert';
 import { registerGetWebhook } from './getWebhook';
 import { registerSaveAlert } from './saveAlert';

packages/api/src/mcp/tools/alerts/saveAlert.ts

@@ -9,13 +9,13 @@ import {
   updateAlert,
   validateAlertInput,
 } from '@/controllers/alerts';
+import type { McpContext } from '@/mcp/tools/types';
+import { mcpError, validateObjectId } from '@/mcp/utils/errors';
+import { withToolTracing } from '@/mcp/utils/tracing';
 import { type AlertChannel, AlertSource } from '@/models/alert';
 import { BaseError } from '@/utils/errors';
 import { translateAlertDocumentToExternalAlert } from '@/utils/externalApi';
 
-import { mcpError, validateObjectId } from '../../utils/errors';
-import { withToolTracing } from '../../utils/tracing';
-import type { McpContext } from '../types';
 import {
   type McpSaveAlertInput,
   mcpSaveAlertSchema,

packages/api/src/mcp/tools/dashboards/deleteDashboard.ts

@@ -3,12 +3,11 @@ import mongoose from 'mongoose';
 import { z } from 'zod';
 
 import { deleteDashboard } from '@/controllers/dashboard';
+import type { McpContext } from '@/mcp/tools/types';
+import { withToolTracing } from '@/mcp/utils/tracing';
 import Dashboard from '@/models/dashboard';
 import { objectIdSchema } from '@/utils/zod';
 
-import { withToolTracing } from '../../utils/tracing';
-import type { McpContext } from '../types';
-
 export function registerDeleteDashboard(
   server: McpServer,
   context: McpContext,

packages/api/src/mcp/tools/dashboards/getDashboard.ts

@@ -4,13 +4,12 @@ import { z } from 'zod';
 
 import * as config from '@/config';
 import { getDashboards } from '@/controllers/dashboard';
+import type { McpContext } from '@/mcp/tools/types';
+import { validateObjectId } from '@/mcp/utils/errors';
+import { withToolTracing } from '@/mcp/utils/tracing';
 import Dashboard from '@/models/dashboard';
 import { convertToExternalDashboard } from '@/routers/external-api/v2/utils/dashboards';
 
-import { validateObjectId } from '../../utils/errors';
-import { withToolTracing } from '../../utils/tracing';
-import type { McpContext } from '../types';
-
 export function registerGetDashboard(
   server: McpServer,
   context: McpContext,

packages/api/src/mcp/tools/dashboards/getDashboardTile.ts

@@ -1,13 +1,12 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 
+import type { McpContext } from '@/mcp/tools/types';
+import { withToolTracing } from '@/mcp/utils/tracing';
 import Dashboard from '@/models/dashboard';
 import { convertToExternalDashboard } from '@/routers/external-api/v2/utils/dashboards';
 import { objectIdSchema } from '@/utils/zod';
 
-import { withToolTracing } from '../../utils/tracing';
-import type { McpContext } from '../types';
-
 export function registerGetDashboardTile(
   server: McpServer,
   context: McpContext,

packages/api/src/mcp/tools/dashboards/index.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
-import type { McpContext, ToolDefinition } from '../types';
+import type { McpContext, ToolDefinition } from '@/mcp/tools/types';
+
 import { registerDeleteDashboard } from './deleteDashboard';
 import { registerGetDashboard } from './getDashboard';
 import { registerGetDashboardTile } from './getDashboardTile';