@daghis/teamcity-mcp 0.1.2

package/src/teamcity/branch-specification-parser.ts

@@ -0,0 +1,238 @@
+/**
+ * BranchSpecificationParser - Parses TeamCity branch specifications
+ */
+
+export interface BranchSpec {
+  pattern: string;
+  type: 'include' | 'exclude';
+  isDefault: boolean;
+  regex?: RegExp;
+}
+
+export interface MatchResult {
+  configId: string;
+  configName: string;
+  matchedSpec: string;
+  confidence: number;
+}
+
+export interface BuildConfiguration {
+  id: string;
+  name: string;
+  branchSpecs: string[];
+}
+
+export class BranchSpecificationParser {
+  /**
+   * Parse a single branch specification
+   */
+  parseSpecification(spec: string): BranchSpec {
+    if (!spec?.trim()) {
+      throw new Error('Empty branch specification');
+    }
+
+    let trimmedSpec = spec.trim();
+    let type: 'include' | 'exclude' = 'include';
+    let isDefault = false;
+
+    // Check for default branch marker
+    if (trimmedSpec.includes('(default)')) {
+      isDefault = true;
+      trimmedSpec = trimmedSpec.replace('(default)', '').trim();
+    }
+
+    // Check for <default> placeholder
+    if (trimmedSpec === '<default>') {
+      return {
+        pattern: '<default>',
+        type: 'include',
+        isDefault: true,
+        regex: new RegExp('^<default>$'),
+      };
+    }
+
+    // Parse inclusion/exclusion prefix
+    if (trimmedSpec.startsWith('+:')) {
+      type = 'include';
+      trimmedSpec = trimmedSpec.substring(2);
+    } else if (trimmedSpec.startsWith('-:')) {
+      type = 'exclude';
+      trimmedSpec = trimmedSpec.substring(2);
+    }
+
+    const pattern = trimmedSpec;
+    const regex = this.convertWildcardToRegex(pattern);
+
+    return {
+      pattern,
+      type,
+      isDefault,
+      regex,
+    };
+  }
+
+  /**
+   * Parse multiple branch specifications
+   */
+  parseMultipleSpecifications(specs: string[] | string): BranchSpec[] {
+    let specList: string[];
+
+    if (typeof specs === 'string') {
+      specList = specs.split('\n');
+    } else {
+      specList = specs;
+    }
+
+    return specList.filter((spec) => spec?.trim()).map((spec) => this.parseSpecification(spec));
+  }
+
+  /**
+   * Convert wildcard pattern to regular expression
+   */
+  convertWildcardToRegex(pattern: string): RegExp {
+    // First, temporarily replace ** to avoid confusion with single *
+    let regexPattern = pattern.replace(/\*\*/g, '___DOUBLE_WILDCARD___');
+
+    // Escape special regex characters except wildcards and parentheses/pipes for groups
+    regexPattern = regexPattern
+      .replace(/[.+?^${}[\]\\]/g, '\\$&') // Escape special chars (but not * ( ) |)
+      .replace(/\*/g, '[^/]*') // Single wildcard matches anything except /
+      .replace(/___DOUBLE_WILDCARD___/g, '.*'); // Double wildcard matches everything
+
+    return new RegExp(`^${regexPattern}$`);
+  }
+
+  /**
+   * Extract default branch from specifications
+   */
+  extractDefaultBranch(specs: BranchSpec[]): string | null {
+    const defaultSpec = specs.find((spec) => spec.isDefault);
+    return defaultSpec ? defaultSpec.pattern : null;
+  }
+
+  /**
+   * Check if a branch matches the given specifications
+   */
+  matchBranch(branchName: string, specs: BranchSpec[]): boolean {
+    let matched = false;
+
+    // Apply rules in order
+    for (const spec of specs) {
+      if (spec.regex && spec.regex.test(branchName)) {
+        if (spec.type === 'include') {
+          matched = true;
+        } else if (spec.type === 'exclude') {
+          matched = false;
+        }
+      }
+    }
+
+    return matched;
+  }
+}
+
+export class BranchMatcher {
+  constructor(private parser: BranchSpecificationParser) {}
+
+  /**
+   * Check if a branch matches the given specifications
+   */
+  matchBranch(branchName: string, specs: BranchSpec[]): boolean {
+    let matched = false;
+
+    // Apply rules in order
+    for (const spec of specs) {
+      if (spec.regex && spec.regex.test(branchName)) {
+        if (spec.type === 'include') {
+          matched = true;
+        } else if (spec.type === 'exclude') {
+          matched = false;
+        }
+      }
+    }
+
+    return matched;
+  }
+
+  /**
+   * Find configurations that can build a specific branch
+   */
+  getMatchingConfigurations(
+    branchName: string,
+    configurations: BuildConfiguration[]
+  ): MatchResult[] {
+    const results: MatchResult[] = [];
+
+    for (const config of configurations) {
+      const specs = this.parser.parseMultipleSpecifications(config.branchSpecs);
+
+      if (this.matchBranch(branchName, specs)) {
+        // Find the spec that matched
+        let matchedSpec = '';
+        let confidence = 0;
+
+        for (const spec of specs) {
+          if (spec.type === 'include' && spec.regex && spec.regex.test(branchName)) {
+            matchedSpec = spec.pattern;
+            confidence = this.calculateConfidence(spec.pattern, branchName);
+            break;
+          }
+        }
+
+        results.push({
+          configId: config.id,
+          configName: config.name,
+          matchedSpec,
+          confidence,
+        });
+      }
+    }
+
+    // Sort by confidence (highest first)
+    return results.sort((a, b) => b.confidence - a.confidence);
+  }
+
+  /**
+   * Calculate confidence score for a match
+   */
+  private calculateConfidence(pattern: string, branchName: string): number {
+    // Exact match
+    if (pattern === branchName) {
+      return 1.0;
+    }
+
+    // Count wildcards to determine specificity
+    const singleWildcards = (pattern.match(/(?<!\*)\*(?!\*)/g) ?? []).length;
+    const doubleWildcards = (pattern.match(/\*\*/g) ?? []).length;
+
+    if (doubleWildcards > 0) {
+      return 0.6; // Least specific
+    } else if (singleWildcards > 0) {
+      return 0.8; // Moderately specific
+    }
+
+    return 0.9; // Pattern with regex groups or other patterns
+  }
+
+  /**
+   * Extract potential branches from configuration specifications
+   */
+  getBranchesForConfiguration(specs: string[]): string[] {
+    const branches: string[] = [];
+    const parsedSpecs = this.parser.parseMultipleSpecifications(specs);
+
+    for (const spec of parsedSpecs) {
+      if (spec.type === 'include') {
+        // For non-wildcard patterns, add them directly
+        if (!spec.pattern.includes('*')) {
+          branches.push(spec.pattern);
+        } else {
+          // For wildcard patterns, add a representative example
+          branches.push(spec.pattern);
+        }
+      }
+    }
+
+    return branches;
+  }
+}

package/src/teamcity/build-config-manager.ts

@@ -0,0 +1,458 @@
+/**
+ * Build Configuration Manager for TeamCity
+ *
+ * Manages listing, filtering, and paginating build configurations
+ * from TeamCity projects.
+ */
+import type { Logger } from 'winston';
+
+import type { BuildType, BuildTypes } from '@/teamcity-client';
+
+import type { TeamCityClient } from './client';
+
+/**
+ * Build configuration with normalized fields
+ */
+export interface ManagedBuildConfiguration {
+  id: string;
+  name: string;
+  projectId: string;
+  projectName: string;
+  description?: string;
+  webUrl?: string;
+  paused: boolean;
+  templateFlag: boolean;
+  templateId?: string;
+  parameters?: Record<string, string>;
+  vcsRootIds?: string[];
+  buildSteps?: number;
+  triggers?: number;
+  dependencies?: {
+    snapshot: string[];
+    artifact: string[];
+  };
+}
+
+/**
+ * Filtering options for build configurations
+ */
+export interface BuildConfigurationFilters {
+  projectId?: string;
+  projectIds?: string[];
+  namePattern?: string;
+  templateFlag?: boolean;
+  paused?: boolean;
+  tags?: string[];
+  hasVcsRoot?: boolean;
+  hasTriggers?: boolean;
+}
+
+/**
+ * Sorting options
+ */
+export interface BuildConfigurationSort {
+  by?: 'name' | 'projectName' | 'id' | 'created' | 'modified';
+  order?: 'asc' | 'desc';
+}
+
+/**
+ * Pagination options
+ */
+export interface BuildConfigurationPagination {
+  page?: number;
+  pageSize?: number;
+}
+
+/**
+ * Response with pagination metadata
+ */
+export interface PaginatedBuildConfigurations {
+  configurations: ManagedBuildConfiguration[];
+  pagination: {
+    page: number;
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+  };
+}
+
+/**
+ * Manager for build configurations
+ */
+export class BuildConfigManager {
+  constructor(
+    private readonly client: TeamCityClient,
+    private readonly logger: Logger
+  ) {}
+
+  /**
+   * List build configurations with filtering and pagination
+   */
+  async listConfigurations(
+    options: {
+      filters?: BuildConfigurationFilters;
+      sort?: BuildConfigurationSort;
+      pagination?: BuildConfigurationPagination;
+      includeDetails?: boolean;
+    } = {}
+  ): Promise<PaginatedBuildConfigurations> {
+    const {
+      filters = {},
+      sort = { by: 'name', order: 'asc' },
+      pagination = { page: 1, pageSize: 50 },
+    } = options;
+
+    try {
+      // Construct locator string for TeamCity API
+      const locator = this.buildLocator(filters);
+
+      // Fetch build types from TeamCity
+      const response = await this.client.buildTypes.getAllBuildTypes(
+        locator,
+        this.buildFieldsSpec(options.includeDetails)
+      );
+
+      const allConfigs = this.normalizeBuildTypes(response.data);
+
+      // Apply additional filtering
+      let filteredConfigs = this.applyFilters(allConfigs, filters);
+
+      // Sort configurations
+      filteredConfigs = this.sortConfigurations(filteredConfigs, sort);
+
+      // Apply pagination
+      const paginatedResult = this.paginate(filteredConfigs, pagination);
+
+      return paginatedResult;
+    } catch (error) {
+      this.logger.error('Failed to list build configurations', { error, options });
+      throw error;
+    }
+  }
+
+  /**
+   * Get configurations by project with hierarchy
+   */
+  async getProjectConfigurations(
+    projectId: string,
+    includeSubprojects: boolean = false
+  ): Promise<ManagedBuildConfiguration[]> {
+    try {
+      const filters: BuildConfigurationFilters = { projectId };
+
+      if (includeSubprojects) {
+        // Get all subprojects
+        const subprojectIds = await this.getSubprojectIds(projectId);
+        filters.projectIds = [projectId, ...subprojectIds];
+        delete filters.projectId;
+      }
+
+      const result = await this.listConfigurations({
+        filters,
+        pagination: { pageSize: 1000 }, // Get all
+      });
+
+      return result.configurations;
+    } catch (error) {
+      this.logger.error('Failed to get project configurations', {
+        error,
+        projectId,
+        includeSubprojects,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Get template hierarchy for configurations
+   */
+  async getTemplateHierarchy(templateId: string): Promise<{
+    template: ManagedBuildConfiguration;
+    inheritors: ManagedBuildConfiguration[];
+  }> {
+    try {
+      // Get the template itself
+      const templateResponse = await this.client.buildTypes.getBuildType(
+        templateId,
+        this.buildFieldsSpec(true)
+      );
+
+      const template = this.normalizeBuildType(templateResponse.data);
+
+      // Find all configurations using this template
+      const allConfigs = await this.listConfigurations({
+        pagination: { pageSize: 1000 },
+      });
+
+      const inheritors = allConfigs.configurations.filter(
+        (config) => config.templateId === templateId
+      );
+
+      return { template, inheritors };
+    } catch (error) {
+      this.logger.error('Failed to get template hierarchy', { error, templateId });
+      throw error;
+    }
+  }
+
+  /**
+   * Build locator string for TeamCity API
+   */
+  private buildLocator(filters: BuildConfigurationFilters): string | undefined {
+    const parts: string[] = [];
+
+    if (filters.projectId) {
+      parts.push(`affectedProject:(id:${filters.projectId})`);
+    } else if (filters.projectIds && filters.projectIds.length > 0) {
+      const projectLocator = filters.projectIds.map((id) => `id:${id}`).join(',');
+      parts.push(`affectedProject:(${projectLocator})`);
+    }
+
+    if (filters.templateFlag !== undefined) {
+      parts.push(`templateFlag:${filters.templateFlag}`);
+    }
+
+    if (filters.paused !== undefined) {
+      parts.push(`paused:${filters.paused}`);
+    }
+
+    if (filters.tags && filters.tags.length > 0) {
+      const tagLocator = filters.tags.join(',');
+      parts.push(`tag:(${tagLocator})`);
+    }
+
+    return parts.length > 0 ? parts.join(',') : undefined;
+  }
+
+  /**
+   * Build fields specification for API request
+   */
+  private buildFieldsSpec(includeDetails?: boolean): string {
+    const baseFields = [
+      'id',
+      'name',
+      'projectId',
+      'projectName',
+      'description',
+      'webUrl',
+      'paused',
+      'templateFlag',
+      'template(id)',
+    ];
+
+    if (includeDetails) {
+      baseFields.push(
+        'parameters(property(name,value))',
+        'vcs-root-entries(vcs-root-entry(id))',
+        'steps(count)',
+        'triggers(count)',
+        'snapshot-dependencies(count)',
+        'artifact-dependencies(count)'
+      );
+    }
+
+    return `buildType(${baseFields.join(',')})`;
+  }
+
+  /**
+   * Normalize build types from API response
+   */
+  private normalizeBuildTypes(response: BuildTypes): ManagedBuildConfiguration[] {
+    const buildTypes = response.buildType ?? [];
+    return buildTypes.map((bt) => this.normalizeBuildType(bt));
+  }
+
+  /**
+   * Normalize a single build type
+   */
+  private normalizeBuildType(buildType: Partial<BuildType>): ManagedBuildConfiguration {
+    const config: ManagedBuildConfiguration = {
+      id: buildType.id ?? '',
+      name: buildType.name ?? '',
+      projectId: buildType.projectId ?? '',
+      projectName: buildType.projectName ?? '',
+      description: buildType.description,
+      webUrl: buildType.webUrl,
+      paused: buildType.paused ?? false,
+      templateFlag: buildType.templateFlag ?? false,
+    };
+
+    // Add template ID if present
+    if (buildType.template?.id) {
+      config.templateId = buildType.template.id;
+    }
+
+    // Add parameters if present
+    if (buildType.parameters?.property) {
+      config.parameters = {};
+      for (const param of buildType.parameters.property) {
+        if (param.name && param.value) {
+          config.parameters[param.name] = param.value;
+        }
+      }
+    }
+
+    // Add VCS root IDs if present
+    if (buildType['vcs-root-entries']?.['vcs-root-entry']) {
+      config.vcsRootIds = buildType['vcs-root-entries']['vcs-root-entry']
+        .map((entry: { id?: string }) => entry.id)
+        .filter((id): id is string => Boolean(id));
+    }
+
+    // Add counts if present
+    if (buildType.steps?.count !== undefined) {
+      config.buildSteps = buildType.steps.count;
+    }
+
+    if (buildType.triggers?.count !== undefined) {
+      config.triggers = buildType.triggers.count;
+    }
+
+    // Add dependencies if present
+    if (buildType['snapshot-dependencies'] ?? buildType['artifact-dependencies']) {
+      config.dependencies = {
+        snapshot: [],
+        artifact: [],
+      };
+
+      if (buildType['snapshot-dependencies']?.['snapshot-dependency']) {
+        config.dependencies.snapshot = buildType['snapshot-dependencies']['snapshot-dependency']
+          .map((dep: { id?: string }) => dep.id)
+          .filter((id): id is string => Boolean(id));
+      }
+
+      if (buildType['artifact-dependencies']?.['artifact-dependency']) {
+        config.dependencies.artifact = buildType['artifact-dependencies']['artifact-dependency']
+          .map((dep: { id?: string }) => dep.id)
+          .filter((id): id is string => Boolean(id));
+      }
+    }
+
+    return config;
+  }
+
+  /**
+   * Apply additional filters not supported by locator
+   */
+  private applyFilters(
+    configurations: ManagedBuildConfiguration[],
+    filters: BuildConfigurationFilters
+  ): ManagedBuildConfiguration[] {
+    let filtered = [...configurations];
+
+    // Filter by name pattern
+    if (filters.namePattern) {
+      const pattern = filters.namePattern.toLowerCase();
+      if (pattern.includes('*')) {
+        // Wildcard pattern
+        const regex = new RegExp(`^${pattern.replace(/\*/g, '.*').replace(/\?/g, '.')}$`, 'i');
+        filtered = filtered.filter((config) => regex.test(config.name));
+      } else {
+        // Simple contains
+        filtered = filtered.filter((config) => config.name.toLowerCase().includes(pattern));
+      }
+    }
+
+    // Filter by VCS root presence
+    if (filters.hasVcsRoot !== undefined) {
+      filtered = filtered.filter((config) => {
+        const hasVcs = config.vcsRootIds && config.vcsRootIds.length > 0;
+        return filters.hasVcsRoot ? hasVcs : !hasVcs;
+      });
+    }
+
+    // Filter by trigger presence
+    if (filters.hasTriggers !== undefined) {
+      filtered = filtered.filter((config) => {
+        const hasTriggers = config.triggers != null && config.triggers > 0;
+        return filters.hasTriggers === true ? hasTriggers : !hasTriggers;
+      });
+    }
+
+    return filtered;
+  }
+
+  /**
+   * Sort configurations
+   */
+  private sortConfigurations(
+    configurations: ManagedBuildConfiguration[],
+    sort: BuildConfigurationSort
+  ): ManagedBuildConfiguration[] {
+    const sorted = [...configurations];
+    const { by = 'name', order = 'asc' } = sort;
+
+    sorted.sort((a, b) => {
+      let comparison = 0;
+
+      switch (by) {
+        case 'name':
+          comparison = a.name.localeCompare(b.name);
+          break;
+        case 'projectName':
+          comparison = a.projectName.localeCompare(b.projectName);
+          break;
+        case 'id':
+          comparison = a.id.localeCompare(b.id);
+          break;
+        default:
+          comparison = 0;
+      }
+
+      return order === 'asc' ? comparison : -comparison;
+    });
+
+    return sorted;
+  }
+
+  /**
+   * Apply pagination
+   */
+  private paginate(
+    configurations: ManagedBuildConfiguration[],
+    pagination: BuildConfigurationPagination
+  ): PaginatedBuildConfigurations {
+    const { page = 1, pageSize = 50 } = pagination;
+    const totalCount = configurations.length;
+    const totalPages = Math.ceil(totalCount / pageSize);
+
+    const startIndex = (page - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+
+    const paginatedConfigs = configurations.slice(startIndex, endIndex);
+
+    return {
+      configurations: paginatedConfigs,
+      pagination: {
+        page,
+        pageSize,
+        totalCount,
+        totalPages,
+        hasNext: page < totalPages,
+        hasPrevious: page > 1,
+      },
+    };
+  }
+
+  /**
+   * Get subproject IDs recursively
+   */
+  private async getSubprojectIds(projectId: string): Promise<string[]> {
+    try {
+      const response = await this.client.projects.getAllSubprojectsOrdered(
+        projectId,
+        'id,parentProjectId'
+      );
+
+      const subprojects = response.data.project ?? [];
+      return subprojects
+        .map((p: { id?: string }) => p.id)
+        .filter((id): id is string => Boolean(id));
+    } catch (error) {
+      this.logger.warn('Failed to get subprojects', { error, projectId });
+      return [];
+    }
+  }
+}