@daghis/teamcity-mcp 0.1.2

package/src/teamcity/configuration-branch-matcher.ts

@@ -0,0 +1,327 @@
+/**
+ * Configuration-Branch Matcher for TeamCity
+ *
+ * Provides bidirectional matching between branches and build configurations,
+ * determining which configurations can build specific branches and vice versa.
+ */
+import type { Logger } from 'winston';
+
+import type { BuildType } from '@/teamcity-client';
+
+import { type BranchSpec, BranchSpecificationParser } from './branch-specification-parser';
+import type { TeamCityClient } from './client';
+
+/**
+ * VCS Root information extracted from build configuration
+ */
+export interface VcsRootInfo {
+  id: string;
+  name: string;
+  defaultBranch?: string;
+  url?: string;
+}
+
+/**
+ * Build configuration that matches a branch
+ */
+export interface MatchedConfiguration {
+  id: string;
+  name: string;
+  projectId: string;
+  matchedSpec: string;
+  confidence: number;
+  vcsRoots?: VcsRootInfo[];
+}
+
+/**
+ * Branch information for a configuration
+ */
+export interface ConfigurationBranches {
+  configId: string;
+  configName: string;
+  defaultBranch?: string;
+  branchSpecs: BranchSpec[];
+  vcsRoots: VcsRootInfo[];
+}
+
+export class ConfigurationBranchMatcher {
+  private parser: BranchSpecificationParser;
+
+  constructor(
+    private readonly client: TeamCityClient,
+    private readonly logger: Logger,
+    parser?: BranchSpecificationParser
+  ) {
+    this.parser = parser ?? new BranchSpecificationParser();
+  }
+
+  /**
+   * Find all build configurations that can build a specific branch
+   */
+  async getConfigurationsForBranch(
+    projectId: string,
+    branchName: string
+  ): Promise<MatchedConfiguration[]> {
+    try {
+      this.logger.debug('Finding configurations for branch', { projectId, branchName });
+
+      // Get all build configurations in the project
+      const buildTypesResponse = await this.client.buildTypes.getAllBuildTypes(
+        `project:(id:${projectId})`
+      );
+
+      if (buildTypesResponse?.data?.buildType == null) {
+        return [];
+      }
+
+      const matchedConfigs: MatchedConfiguration[] = [];
+
+      // Check each configuration
+      for (const buildType of buildTypesResponse.data.buildType) {
+        try {
+          // Get full build type details including VCS roots
+          if (buildType.id == null || buildType.id.length === 0) {
+            continue;
+          }
+          // Intentional per-config fetch to evaluate branch specs and VCS roots
+          // eslint-disable-next-line no-await-in-loop
+          const fullBuildTypeResponse = await this.client.buildTypes.getBuildType(buildType.id);
+          const fullBuildType = fullBuildTypeResponse.data;
+
+          // Extract branch specification
+          const branchSpec = this.extractBranchSpecification(fullBuildType);
+          const vcsRoots = this.extractVcsRoots(fullBuildType);
+
+          // Check if branch matches
+          let matched = false;
+          let matchedSpec = '';
+          let confidence = 0;
+
+          if (!branchSpec) {
+            // No branch spec means only default branch
+            const defaultBranch = vcsRoots[0]?.defaultBranch ?? 'refs/heads/main';
+            if (branchName === defaultBranch || branchName === 'main' || branchName === 'master') {
+              matched = true;
+              matchedSpec = '<default>';
+              confidence = 1.0;
+            }
+          } else {
+            // Parse and check branch specifications
+            const specs = this.parser.parseMultipleSpecifications(branchSpec);
+            const branchToTest = branchName.startsWith('refs/heads/')
+              ? branchName
+              : `refs/heads/${branchName}`;
+
+            matched = this.parser.matchBranch(branchToTest, specs);
+
+            if (matched) {
+              // Find the matching spec
+              for (const spec of specs) {
+                if (spec.type === 'include' && this.testBranchAgainstSpec(branchToTest, spec)) {
+                  matchedSpec = spec.pattern;
+                  confidence = this.calculateConfidence(spec.pattern);
+                  break;
+                }
+              }
+            }
+          }
+
+          if (
+            matched &&
+            buildType.id != null &&
+            buildType.id.length > 0 &&
+            buildType.name != null &&
+            buildType.name.length > 0 &&
+            buildType.projectId != null &&
+            buildType.projectId.length > 0
+          ) {
+            matchedConfigs.push({
+              id: buildType.id,
+              name: buildType.name,
+              projectId: buildType.projectId,
+              matchedSpec,
+              confidence,
+              vcsRoots,
+            });
+          }
+        } catch (error) {
+          this.logger.error('Failed to check configuration', {
+            configId: buildType.id,
+            error,
+          });
+        }
+      }
+
+      // Sort by confidence (highest first)
+      matchedConfigs.sort((a, b) => b.confidence - a.confidence);
+
+      this.logger.debug('Found matching configurations', {
+        branchName,
+        count: matchedConfigs.length,
+      });
+
+      return matchedConfigs;
+    } catch (error) {
+      this.logger.error('Failed to get configurations for branch', {
+        projectId,
+        branchName,
+        error,
+      });
+      return [];
+    }
+  }
+
+  /**
+   * Get all branches that can be built by a specific configuration
+   */
+  async getBranchesForConfiguration(configId: string): Promise<ConfigurationBranches> {
+    try {
+      this.logger.debug('Getting branches for configuration', { configId });
+
+      // Get full build type details
+      const buildTypeResponse = await this.client.buildTypes.getBuildType(configId);
+      const buildType = buildTypeResponse.data;
+
+      // Extract branch specification and VCS roots
+      const branchSpec = this.extractBranchSpecification(buildType);
+      const vcsRoots = this.extractVcsRoots(buildType);
+      const defaultBranch = vcsRoots[0]?.defaultBranch;
+
+      // Parse branch specifications
+      let branchSpecs: BranchSpec[];
+      if (!branchSpec) {
+        // No spec means only default branch
+        branchSpecs = [
+          {
+            pattern: '<default>',
+            type: 'include',
+            isDefault: true,
+          },
+        ];
+      } else {
+        branchSpecs = this.parser.parseMultipleSpecifications(branchSpec);
+      }
+
+      return {
+        configId: buildType.id ?? 'unknown',
+        configName: buildType.name ?? 'Unknown',
+        defaultBranch,
+        branchSpecs,
+        vcsRoots,
+      };
+    } catch (error) {
+      this.logger.error('Failed to get branches for configuration', {
+        configId,
+        error,
+      });
+
+      return {
+        configId,
+        configName: 'Unknown',
+        branchSpecs: [],
+        vcsRoots: [],
+      };
+    }
+  }
+
+  /**
+   * Extract branch specification from build type parameters
+   */
+  private extractBranchSpecification(buildType: BuildType): string {
+    const properties = buildType.parameters?.property;
+    if (!properties) {
+      return '';
+    }
+
+    const branchFilterParam = properties.find(
+      (prop) => prop.name === 'teamcity.vcsTrigger.branchFilter'
+    );
+
+    return branchFilterParam?.value ?? '';
+  }
+
+  /**
+   * Extract VCS root information from build type
+   */
+  private extractVcsRoots(buildType: BuildType): VcsRootInfo[] {
+    const roots: VcsRootInfo[] = [];
+
+    if (!buildType['vcs-root-entries']?.['vcs-root-entry']) {
+      return roots;
+    }
+
+    for (const entry of buildType['vcs-root-entries']['vcs-root-entry']) {
+      const vcsRoot = entry['vcs-root'];
+      if (!vcsRoot) {
+        continue;
+      }
+
+      const properties = vcsRoot.properties?.property ?? [];
+      const branchProp = properties.find((p) => p.name === 'branch');
+      const urlProp = properties.find((p) => p.name === 'url');
+
+      if (
+        vcsRoot.id != null &&
+        vcsRoot.id.length > 0 &&
+        vcsRoot.name != null &&
+        vcsRoot.name.length > 0
+      ) {
+        roots.push({
+          id: vcsRoot.id,
+          name: vcsRoot.name,
+          defaultBranch: branchProp?.value,
+          url: urlProp?.value,
+        });
+      }
+    }
+
+    return roots;
+  }
+
+  /**
+   * Test if a branch matches a specific branch specification
+   */
+  private testBranchAgainstSpec(branchName: string, spec: BranchSpec): boolean {
+    if (spec.regex) {
+      return spec.regex.test(branchName);
+    }
+
+    // Fallback to simple pattern matching
+    const pattern = spec.pattern.replace(/\*/g, '.*').replace(/\?/g, '.');
+
+    const regex = new RegExp(`^${pattern}$`);
+    return regex.test(branchName);
+  }
+
+  /**
+   * Calculate confidence score based on pattern specificity
+   */
+  private calculateConfidence(pattern: string): number {
+    // Exact match (no wildcards)
+    if (!pattern.includes('*') && !pattern.includes('?')) {
+      return 1.0;
+    }
+
+    // Regex groups - check before wildcards since they can contain wildcards
+    if (pattern.includes('(') && pattern.includes(')')) {
+      return 0.8;
+    }
+
+    // Single wildcard
+    if (pattern.split('*').length === 2 && !pattern.includes('**')) {
+      return 0.9;
+    }
+
+    // Double wildcard
+    if (pattern.includes('**')) {
+      // Complex pattern with multiple wildcards
+      if (pattern.split('*').length > 3) {
+        return 0.6;
+      }
+      return 0.7;
+    }
+
+    // Default for other patterns
+    return 0.5;
+  }
+}

package/src/teamcity/errors.ts

@@ -0,0 +1,351 @@
+/**
+ * Custom error classes for TeamCity API operations
+ */
+import type { AxiosError } from 'axios';
+
+/**
+ * Base error class for all TeamCity API errors
+ */
+export class TeamCityAPIError extends Error {
+  public readonly code: string;
+  public readonly statusCode?: number;
+  public readonly details?: unknown;
+  public readonly requestId?: string;
+  public readonly originalError?: Error;
+
+  constructor(
+    message: string,
+    code: string,
+    statusCode?: number,
+    details?: unknown,
+    requestId?: string,
+    originalError?: Error
+  ) {
+    super(message);
+    this.name = 'TeamCityAPIError';
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.requestId = requestId;
+    this.originalError = originalError;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (typeof Error.captureStackTrace === 'function') {
+      Error.captureStackTrace(this, TeamCityAPIError);
+    }
+  }
+
+  /**
+   * Create from Axios error
+   */
+  static fromAxiosError(error: AxiosError, requestId?: string): TeamCityAPIError {
+    if (error.response) {
+      // Server responded with error status
+      const data = error.response.data as Record<string, unknown>;
+      return new TeamCityAPIError(
+        (typeof data?.['message'] === 'string' ? data['message'] : null) ?? error.message,
+        (typeof data?.['code'] === 'string' ? data['code'] : null) ??
+          `HTTP_${error.response.status}`,
+        error.response.status,
+        data,
+        requestId,
+        error
+      );
+    } else if (error.request !== null && error.request !== undefined) {
+      // Request made but no response
+      return new TeamCityNetworkError(error.message, requestId, error);
+    } else {
+      // Error setting up request
+      return new TeamCityRequestError(error.message, requestId, error);
+    }
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details,
+      requestId: this.requestId,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Authentication error (401)
+ */
+export class TeamCityAuthenticationError extends TeamCityAPIError {
+  constructor(message = 'Authentication failed', requestId?: string, originalError?: Error) {
+    super(message, 'AUTHENTICATION_ERROR', 401, undefined, requestId, originalError);
+    this.name = 'TeamCityAuthenticationError';
+  }
+}
+
+/**
+ * Authorization error (403)
+ */
+export class TeamCityAuthorizationError extends TeamCityAPIError {
+  constructor(message = 'Authorization failed', requestId?: string, originalError?: Error) {
+    super(message, 'AUTHORIZATION_ERROR', 403, undefined, requestId, originalError);
+    this.name = 'TeamCityAuthorizationError';
+  }
+}
+
+/**
+ * Resource not found error (404)
+ */
+export class TeamCityNotFoundError extends TeamCityAPIError {
+  constructor(resource: string, identifier?: string, requestId?: string, originalError?: Error) {
+    const message =
+      identifier !== null && identifier !== undefined
+        ? `${resource} with identifier '${identifier}' not found`
+        : `${resource} not found`;
+    super(message, 'NOT_FOUND', 404, { resource, identifier }, requestId, originalError);
+    this.name = 'TeamCityNotFoundError';
+  }
+}
+
+/**
+ * Validation error (400)
+ */
+export class TeamCityValidationError extends TeamCityAPIError {
+  public readonly validationErrors: Array<{ field: string; message: string }>;
+
+  constructor(
+    validationErrors: Array<{ field: string; message: string }>,
+    requestId?: string,
+    originalError?: Error
+  ) {
+    const message = `Validation failed: ${validationErrors.map((e) => e.message).join(', ')}`;
+    super(message, 'VALIDATION_ERROR', 400, validationErrors, requestId, originalError);
+    this.name = 'TeamCityValidationError';
+    this.validationErrors = validationErrors;
+  }
+}
+
+/**
+ * Rate limit error (429)
+ */
+export class TeamCityRateLimitError extends TeamCityAPIError {
+  public readonly retryAfter?: number;
+
+  constructor(retryAfter?: number, requestId?: string, originalError?: Error) {
+    const message =
+      retryAfter !== null && retryAfter !== undefined
+        ? `Rate limit exceeded. Retry after ${retryAfter} seconds`
+        : 'Rate limit exceeded';
+    super(message, 'RATE_LIMIT_ERROR', 429, { retryAfter }, requestId, originalError);
+    this.name = 'TeamCityRateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Server error (5xx)
+ */
+export class TeamCityServerError extends TeamCityAPIError {
+  constructor(
+    message = 'TeamCity server error',
+    statusCode = 500,
+    requestId?: string,
+    originalError?: Error
+  ) {
+    super(message, 'SERVER_ERROR', statusCode, undefined, requestId, originalError);
+    this.name = 'TeamCityServerError';
+  }
+}
+
+/**
+ * Network error
+ */
+export class TeamCityNetworkError extends TeamCityAPIError {
+  constructor(message = 'Network error', requestId?: string, originalError?: Error) {
+    super(message, 'NETWORK_ERROR', undefined, undefined, requestId, originalError);
+    this.name = 'TeamCityNetworkError';
+  }
+}
+
+/**
+ * Request configuration error
+ */
+export class TeamCityRequestError extends TeamCityAPIError {
+  constructor(message = 'Request configuration error', requestId?: string, originalError?: Error) {
+    super(message, 'REQUEST_ERROR', undefined, undefined, requestId, originalError);
+    this.name = 'TeamCityRequestError';
+  }
+}
+
+/**
+ * Timeout error
+ */
+export class TeamCityTimeoutError extends TeamCityAPIError {
+  constructor(timeout: number, requestId?: string, originalError?: Error) {
+    super(
+      `Request timed out after ${timeout}ms`,
+      'TIMEOUT_ERROR',
+      undefined,
+      { timeout },
+      requestId,
+      originalError
+    );
+    this.name = 'TeamCityTimeoutError';
+  }
+}
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryableError(error: Error): boolean {
+  if (error instanceof TeamCityAPIError) {
+    // Network errors are retryable
+    if (error instanceof TeamCityNetworkError) {
+      return true;
+    }
+
+    // Timeout errors are retryable
+    if (error instanceof TeamCityTimeoutError) {
+      return true;
+    }
+
+    // Server errors (5xx) are retryable
+    if (error instanceof TeamCityServerError) {
+      return true;
+    }
+
+    // Rate limit errors are retryable after delay
+    if (error instanceof TeamCityRateLimitError) {
+      return true;
+    }
+
+    // 503 Service Unavailable is retryable
+    if (error.statusCode === 503) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Build not found error
+ */
+export class BuildNotFoundError extends TeamCityNotFoundError {
+  constructor(message: string, requestId?: string, originalError?: Error) {
+    super('Build', message, requestId, originalError);
+    this.name = 'BuildNotFoundError';
+  }
+}
+
+/**
+ * Build access denied error
+ */
+export class BuildAccessDeniedError extends TeamCityAuthorizationError {
+  constructor(message: string, requestId?: string, originalError?: Error) {
+    super(message, requestId, originalError);
+    this.name = 'BuildAccessDeniedError';
+  }
+}
+
+/**
+ * Build configuration not found error
+ */
+export class BuildConfigurationNotFoundError extends TeamCityNotFoundError {
+  constructor(message: string, requestId?: string, originalError?: Error) {
+    super('Build Configuration', message, requestId, originalError);
+    this.name = 'BuildConfigurationNotFoundError';
+  }
+}
+
+/**
+ * Build configuration permission error
+ */
+export class BuildConfigurationPermissionError extends TeamCityAuthorizationError {
+  public readonly buildConfigurationId?: string;
+
+  constructor(message: string, configId?: string, requestId?: string, originalError?: Error) {
+    super(message, requestId, originalError);
+    this.name = 'BuildConfigurationPermissionError';
+    this.buildConfigurationId = configId;
+  }
+}
+
+/**
+ * Build step not found error
+ */
+export class BuildStepNotFoundError extends TeamCityNotFoundError {
+  constructor(message: string, stepId: string, requestId?: string, originalError?: Error) {
+    super('Build Step', stepId, requestId, originalError);
+    this.name = 'BuildStepNotFoundError';
+  }
+}
+
+/**
+ * Permission denied error
+ */
+export class PermissionDeniedError extends TeamCityAuthorizationError {
+  constructor(message: string, operation: string, requestId?: string, originalError?: Error) {
+    super(`${message} (operation: ${operation})`, requestId, originalError);
+    this.name = 'PermissionDeniedError';
+  }
+}
+
+/**
+ * Validation error with field details
+ */
+export class ValidationError extends TeamCityValidationError {
+  public readonly fieldDetails?: unknown;
+
+  constructor(message: string, details?: unknown, requestId?: string, originalError?: Error) {
+    const detailsObj = details as { field?: string } | undefined;
+    const validationErrors =
+      detailsObj?.field !== null && detailsObj?.field !== undefined
+        ? [{ field: detailsObj.field, message }]
+        : [{ field: 'unknown', message }];
+    super(validationErrors, requestId, originalError);
+    this.fieldDetails = details;
+  }
+}
+
+/**
+ * Trigger not found error
+ */
+export class TriggerNotFoundError extends TeamCityNotFoundError {
+  constructor(message: string, triggerId: string, requestId?: string, originalError?: Error) {
+    super('Trigger', triggerId, requestId, originalError);
+    this.name = 'TriggerNotFoundError';
+  }
+}
+
+/**
+ * Circular dependency error
+ */
+export class CircularDependencyError extends TeamCityValidationError {
+  public readonly dependencyDetails?: unknown;
+
+  constructor(message: string, details?: unknown, requestId?: string, originalError?: Error) {
+    super([{ field: 'dependency', message }], requestId, originalError);
+    this.name = 'CircularDependencyError';
+    this.dependencyDetails = details;
+  }
+}
+
+/**
+ * Get retry delay for error
+ */
+export function getRetryDelay(error: Error, attempt: number, baseDelay = 1000): number {
+  // Rate limit error with specific retry-after
+  if (
+    error instanceof TeamCityRateLimitError &&
+    error.retryAfter !== null &&
+    error.retryAfter !== undefined
+  ) {
+    return error.retryAfter * 1000;
+  }
+
+  // Exponential backoff with jitter
+  const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
+  const jitter = Math.random() * 1000;
+  return Math.min(exponentialDelay + jitter, 30000); // Max 30 seconds
+}