@daghis/teamcity-mcp 0.1.2

package/src/teamcity/branch-discovery-manager.ts

@@ -0,0 +1,311 @@
+/**
+ * BranchDiscoveryManager - Discovers branches from TeamCity build history
+ */
+import type { VcsRoot } from '@/teamcity-client/models';
+import { debug, error as logError } from '@/utils/logger';
+
+import type { TeamCityClient } from './client';
+
+export interface BranchInfo {
+  name: string;
+  displayName: string;
+  isDefault: boolean;
+  isActive: boolean;
+  buildCount: number;
+  lastBuild?: {
+    id: string;
+    number: string;
+    status: string;
+    date: string;
+    webUrl?: string;
+  };
+  firstSeenDate?: string;
+  lastActivityDate?: string;
+  vcsRoot?: {
+    id: string;
+    name: string;
+    url: string;
+  };
+}
+
+export interface DiscoveryOptions {
+  limit?: number;
+  fromDate?: Date;
+  toDate?: Date;
+  includeVcsInfo?: boolean;
+}
+
+export class BranchDiscoveryManager {
+  constructor(private readonly client: TeamCityClient) {}
+
+  /**
+   * Discover branches from build history for a specific build configuration
+   */
+  async discoverBranchesFromHistory(
+    buildTypeId: string,
+    options: DiscoveryOptions = {}
+  ): Promise<BranchInfo[]> {
+    try {
+      const { limit = 1000, fromDate, toDate, includeVcsInfo = false } = options;
+
+      // Build the locator string for querying builds
+      const locatorParts = [
+        `buildType:(id:${buildTypeId})`,
+        'branch:(policy:ALL_BRANCHES)',
+        `count:${limit}`,
+      ];
+
+      if (fromDate ?? toDate) {
+        const dateConditions = [];
+        if (fromDate) {
+          dateConditions.push(`date:[${fromDate.toISOString()}]`);
+        }
+        if (toDate) {
+          dateConditions.push(`date:[,${toDate.toISOString()}]`);
+        }
+        if (fromDate && toDate) {
+          locatorParts.push(`startDate:(date:[${fromDate.toISOString()},${toDate.toISOString()}])`);
+        } else if (fromDate) {
+          locatorParts.push(`startDate:(date:[${fromDate.toISOString()},])`);
+        } else if (toDate) {
+          locatorParts.push(`startDate:(date:[,${toDate.toISOString()}])`);
+        }
+      }
+
+      const locator = locatorParts.join(',');
+      const fields =
+        'build(id,buildTypeId,branchName,number,status,startDate,finishDate,webUrl,revisions(revision(vcsRootInstance(id,name,vcsRootId))))';
+
+      debug(`Discovering branches for buildType: ${buildTypeId} with locator: ${locator}`);
+
+      // Query builds from TeamCity
+      const response = await this.client.builds.getMultipleBuilds(locator, fields);
+
+      const buildsResponse = response.data;
+      const builds = buildsResponse.build ?? [];
+
+      // Process builds to extract branch information
+      const branchMap = new Map<string, BranchInfo>();
+
+      for (const build of builds) {
+        if (build.branchName == null) {
+          continue;
+        }
+
+        const branchName = build.branchName;
+        const existingBranch = branchMap.get(branchName);
+
+        if (!existingBranch) {
+          // First time seeing this branch
+          const branchInfo: BranchInfo = {
+            name: branchName,
+            displayName: this.parseBranchDisplayName(branchName),
+            isDefault:
+              branchName === '<default>' || branchName === 'master' || branchName === 'main',
+            isActive: false, // Will be determined later
+            buildCount: 1,
+            lastBuild: {
+              id: build.id?.toString() ?? '',
+              number: build.number ?? '',
+              status: build.status ?? 'UNKNOWN',
+              date: build.startDate ?? '',
+              webUrl: build.webUrl,
+            },
+            firstSeenDate: build.startDate,
+            lastActivityDate: build.startDate,
+          };
+
+          // Add VCS root information if requested and available
+          // Note: Simplified for now - VCS root details would need additional API calls
+          if (
+            includeVcsInfo === true &&
+            build.revisions?.revision != null &&
+            build.revisions.revision.length > 0
+          ) {
+            const revision = build.revisions.revision[0];
+            if (revision?.['vcs-root-instance'] != null) {
+              const vcsRootInstance = revision['vcs-root-instance'];
+              branchInfo.vcsRoot = {
+                id: vcsRootInstance['vcs-root-id'] ?? '',
+                name: vcsRootInstance.name ?? '',
+                url: '', // Would need additional API call to get URL
+              };
+            }
+          }
+
+          branchMap.set(branchName, branchInfo);
+        } else {
+          // Update existing branch info
+          existingBranch.buildCount++;
+
+          // Update last build if this one is more recent
+          if (build.startDate != null) {
+            if (existingBranch.lastActivityDate == null) {
+              existingBranch.lastBuild = {
+                id: build.id?.toString() ?? '',
+                number: build.number ?? '',
+                status: build.status ?? 'UNKNOWN',
+                date: build.startDate ?? '',
+                webUrl: build.webUrl,
+              };
+              existingBranch.lastActivityDate = build.startDate;
+            } else {
+              const buildDate = this.parseDate(build.startDate);
+              const lastActivityDate = this.parseDate(existingBranch.lastActivityDate);
+              if (buildDate > lastActivityDate) {
+                existingBranch.lastBuild = {
+                  id: build.id?.toString() ?? '',
+                  number: build.number ?? '',
+                  status: build.status ?? 'UNKNOWN',
+                  date: build.startDate ?? '',
+                  webUrl: build.webUrl,
+                };
+                existingBranch.lastActivityDate = build.startDate;
+              }
+            }
+          }
+
+          // Update first seen date if this one is older
+          if (build.startDate != null) {
+            if (!existingBranch.firstSeenDate) {
+              existingBranch.firstSeenDate = build.startDate;
+            } else {
+              const buildDate = this.parseDate(build.startDate);
+              const firstSeenDate = this.parseDate(existingBranch.firstSeenDate);
+              if (buildDate < firstSeenDate) {
+                existingBranch.firstSeenDate = build.startDate;
+              }
+            }
+          }
+        }
+      }
+
+      // Convert map to array and detect activity
+      const branches = Array.from(branchMap.values());
+
+      // Detect branch activity
+      return branches.map((branch) => this.detectBranchActivity(branch));
+    } catch (err) {
+      const error = err as Error;
+      logError('Failed to discover branches from history', error);
+      throw new Error(`Failed to discover branches from history: ${error.message}`);
+    }
+  }
+
+  /**
+   * Enrich branch information with latest build data
+   */
+  async enrichBranchWithBuildInfo(branch: BranchInfo, buildTypeId: string): Promise<BranchInfo> {
+    try {
+      const locator = `buildType:(id:${buildTypeId}),branch:(name:${branch.name}),count:1`;
+      const fields = 'build(id,number,status,startDate,finishDate,webUrl)';
+
+      const response = await this.client.builds.getMultipleBuilds(locator, fields);
+
+      const buildsResponse = response.data;
+      const builds = buildsResponse.build ?? [];
+
+      if (builds.length > 0) {
+        const latestBuild = builds[0];
+        if (latestBuild != null) {
+          // Return a new object instead of mutating the parameter
+          return {
+            ...branch,
+            lastBuild: {
+              id: latestBuild.id?.toString() ?? '',
+              number: latestBuild.number ?? '',
+              status: latestBuild.status ?? 'UNKNOWN',
+              date: latestBuild.startDate ?? '',
+              webUrl: latestBuild.webUrl,
+            },
+            buildCount: buildsResponse.count ?? 1,
+            lastActivityDate: latestBuild.startDate,
+          };
+        }
+      }
+
+      return branch;
+    } catch (err) {
+      debug(`Failed to enrich branch ${branch.name}: ${err}`);
+      return branch;
+    }
+  }
+
+  /**
+   * Detect if a branch is active based on recent activity
+   */
+  detectBranchActivity(branch: BranchInfo, thresholdDays: number = 30): BranchInfo {
+    if (!branch.lastActivityDate) {
+      branch.isActive = false;
+      return branch;
+    }
+
+    const now = new Date();
+    const lastActivity = this.parseDate(branch.lastActivityDate);
+    const daysSinceActivity = (now.getTime() - lastActivity.getTime()) / (1000 * 60 * 60 * 24);
+
+    branch.isActive = daysSinceActivity <= thresholdDays;
+
+    return branch;
+  }
+
+  /**
+   * Parse branch name to create a display-friendly version
+   */
+  parseBranchDisplayName(branchName: string): string {
+    // Handle Git refs
+    if (branchName.startsWith('refs/heads/')) {
+      return branchName.replace('refs/heads/', '');
+    }
+    if (branchName.startsWith('refs/tags/')) {
+      return branchName.replace('refs/tags/', '');
+    }
+
+    // Handle pull requests
+    const prMatch = branchName.match(/^pull\/(\d+)\/(head|merge)$/);
+    if (prMatch) {
+      return `PR #${prMatch[1]}`;
+    }
+
+    // Handle merge requests (GitLab style)
+    const mrMatch = branchName.match(/^merge-requests\/(\d+)\/(head|merge)$/);
+    if (mrMatch) {
+      return `MR #${mrMatch[1]}`;
+    }
+
+    // Handle special branches
+    if (branchName === '<default>') {
+      return 'default';
+    }
+
+    // Return as-is for other patterns
+    return branchName;
+  }
+
+  /**
+   * Parse TeamCity date format to JavaScript Date
+   */
+  private parseDate(dateString: string): Date {
+    // TeamCity format: 20250829T100000+0000
+    return new Date(
+      dateString
+        .replace(/(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})([+-]\d{4})/, '$1-$2-$3T$4:$5:$6$7')
+        .replace(/([+-]\d{2})(\d{2})$/, '$1:$2')
+    );
+  }
+
+  /**
+   * Extract VCS URL from VcsRoot object
+   */
+  private extractVcsUrl(vcsRoot: VcsRoot): string {
+    if (!vcsRoot.properties?.property) {
+      return '';
+    }
+
+    const urlProperty = vcsRoot.properties.property.find(
+      (p) => p.name === 'url' || p.name === 'repositoryURL'
+    );
+
+    return urlProperty?.value ?? '';
+  }
+}

package/src/teamcity/branch-filtering-service.ts

@@ -0,0 +1,369 @@
+/**
+ * Branch Filtering and Pagination Service for TeamCity
+ *
+ * Provides comprehensive filtering, sorting, and pagination capabilities
+ * for branch discovery results, with intelligent prioritization of active branches.
+ */
+import type { Logger } from 'winston';
+
+/**
+ * Extended BranchInfo with proper Date types for filtering
+ */
+export interface BranchInfo {
+  name: string;
+  displayName: string;
+  isDefault: boolean;
+  isActive: boolean;
+  buildCount: number;
+  lastBuild?: {
+    id: string;
+    number: string;
+    status: string;
+    date: Date | string;
+    webUrl?: string;
+  };
+  firstSeenDate?: Date | string;
+  lastActivityDate?: Date | string;
+  vcsRoot?: {
+    id: string;
+    name: string;
+    url: string;
+  };
+}
+
+/**
+ * Options for filtering branches
+ */
+export interface BranchFilterOptions {
+  /** Pattern to match branch names (supports wildcards and regex) */
+  namePattern?: string;
+  /** Case-insensitive pattern matching */
+  caseInsensitive?: boolean;
+  /** Only return active branches */
+  onlyActive?: boolean;
+  /** Only return default branches */
+  onlyDefault?: boolean;
+  /** Branches active since this date */
+  activeSince?: Date;
+  /** Branches active before this date */
+  activeBefore?: Date;
+  /** Minimum number of builds */
+  minBuildCount?: number;
+  /** Filter by last build status */
+  lastBuildStatus?: 'SUCCESS' | 'FAILURE' | 'ERROR' | 'UNKNOWN';
+}
+
+/**
+ * Options for sorting branches
+ */
+export interface BranchSortOptions {
+  /** Field to sort by */
+  sortBy?: 'name' | 'activity' | 'buildCount' | 'status';
+  /** Sort order */
+  sortOrder?: 'asc' | 'desc';
+  /** Put default branch first regardless of sorting */
+  defaultFirst?: boolean;
+}
+
+/**
+ * Options for paginating branches
+ */
+export interface BranchPaginationOptions {
+  /** Page number (1-based) */
+  page?: number;
+  /** Number of items per page */
+  pageSize?: number;
+  /** Prioritize active branches in results */
+  prioritizeActive?: boolean;
+}
+
+/**
+ * Paginated result of branches
+ */
+export interface PaginatedBranches {
+  /** Branches for current page */
+  branches: BranchInfo[];
+  /** Total number of branches (before pagination) */
+  totalCount: number;
+  /** Current page number */
+  currentPage: number;
+  /** Total number of pages */
+  totalPages: number;
+  /** Whether there are more pages */
+  hasMore: boolean;
+}
+
+export class BranchFilteringService {
+  private readonly defaultPageSize = 20;
+
+  constructor(private readonly logger: Logger) {}
+
+  /**
+   * Filter branches based on provided options
+   */
+  filterBranches(branches: BranchInfo[], options: BranchFilterOptions): BranchInfo[] {
+    let filtered = [...branches];
+
+    // Apply name pattern filter
+    if (options.namePattern) {
+      filtered = this.filterByNamePattern(filtered, options.namePattern, options.caseInsensitive);
+    }
+
+    // Apply activity filters
+    if (options.onlyActive !== undefined) {
+      filtered = filtered.filter((b) => b.isActive === options.onlyActive);
+    }
+
+    if (options.onlyDefault !== undefined) {
+      filtered = filtered.filter((b) => b.isDefault === options.onlyDefault);
+    }
+
+    if (options.activeSince != null) {
+      const activeSince = options.activeSince;
+      filtered = filtered.filter((b) => {
+        if (b.lastActivityDate == null) {
+          return false;
+        }
+        const activityDate = this.toDate(b.lastActivityDate);
+        return activityDate != null && activeSince != null && activityDate >= activeSince;
+      });
+    }
+
+    if (options.activeBefore != null) {
+      const activeBefore = options.activeBefore;
+      filtered = filtered.filter((b) => {
+        if (b.lastActivityDate == null) {
+          return false;
+        }
+        const activityDate = this.toDate(b.lastActivityDate);
+        return activityDate != null && activeBefore != null && activityDate < activeBefore;
+      });
+    }
+
+    if (options.minBuildCount !== undefined) {
+      const minBuildCount = options.minBuildCount as number;
+      filtered = filtered.filter((b) => b.buildCount >= minBuildCount);
+    }
+
+    // Apply status filter
+    if (options.lastBuildStatus) {
+      filtered = filtered.filter((b) => b.lastBuild?.status === options.lastBuildStatus);
+    }
+
+    this.logger.debug('Filtered branches', {
+      originalCount: branches.length,
+      filteredCount: filtered.length,
+      options,
+    });
+
+    return filtered;
+  }
+
+  /**
+   * Sort branches based on provided options
+   */
+  sortBranches(
+    branches: BranchInfo[],
+    sortBy: BranchSortOptions['sortBy'] = 'name',
+    sortOrder: BranchSortOptions['sortOrder'] = 'asc',
+    defaultFirst: boolean = false
+  ): BranchInfo[] {
+    const sorted = [...branches];
+
+    // Define sort comparators
+    const comparators: Record<string, (a: BranchInfo, b: BranchInfo) => number> = {
+      name: (a, b) => a.displayName.localeCompare(b.displayName),
+      activity: (a, b) => {
+        const aDate = this.toDate(a.lastActivityDate)?.getTime() ?? 0;
+        const bDate = this.toDate(b.lastActivityDate)?.getTime() ?? 0;
+        return bDate - aDate; // More recent first
+      },
+      buildCount: (a, b) => b.buildCount - a.buildCount, // Higher count first
+      status: (a, b) => {
+        const statusOrder: Record<string, number> = {
+          SUCCESS: 0,
+          UNKNOWN: 1,
+          ERROR: 2,
+          FAILURE: 3,
+        };
+        const aStatus = a.lastBuild?.status ?? 'UNKNOWN';
+        const bStatus = b.lastBuild?.status ?? 'UNKNOWN';
+        return (statusOrder[aStatus] ?? 99) - (statusOrder[bStatus] ?? 99);
+      },
+    };
+
+    const comparator = comparators[sortBy] ?? comparators['name'];
+
+    sorted.sort((a, b) => {
+      // Default branch always first if requested
+      if (defaultFirst) {
+        if (a.isDefault && !b.isDefault) {
+          return -1;
+        }
+        if (!a.isDefault && b.isDefault) {
+          return 1;
+        }
+      }
+
+      const result = comparator ? comparator(a, b) : 0;
+      return sortOrder === 'desc' && sortBy === 'name'
+        ? -result
+        : sortOrder === 'asc' && sortBy !== 'name'
+          ? -result
+          : result;
+    });
+
+    return sorted;
+  }
+
+  /**
+   * Paginate branches with optional intelligent prioritization
+   */
+  paginateBranches(branches: BranchInfo[], options: BranchPaginationOptions): PaginatedBranches {
+    const page = Math.max(1, options.page ?? 1);
+    const pageSize =
+      options.pageSize && options.pageSize > 0 ? options.pageSize : this.defaultPageSize;
+
+    let branchesToPaginate = [...branches];
+
+    // Apply intelligent prioritization if requested
+    if (options.prioritizeActive) {
+      branchesToPaginate = this.prioritizeBranches(branchesToPaginate);
+    }
+
+    const totalCount = branchesToPaginate.length;
+    const totalPages = Math.ceil(totalCount / pageSize);
+    const startIndex = (page - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+
+    const paginatedBranches = branchesToPaginate.slice(startIndex, endIndex);
+
+    return {
+      branches: paginatedBranches,
+      totalCount,
+      currentPage: page,
+      totalPages,
+      hasMore: page < totalPages,
+    };
+  }
+
+  /**
+   * Apply filters, sorting, and pagination in one operation
+   */
+  applyFiltersAndPagination(
+    branches: BranchInfo[],
+    filterOptions: BranchFilterOptions,
+    sortOptions: BranchSortOptions,
+    paginationOptions: BranchPaginationOptions
+  ): PaginatedBranches {
+    // Step 1: Filter
+    let result = this.filterBranches(branches, filterOptions);
+
+    // Step 2: Sort
+    const shouldSort = sortOptions.sortBy != null ? true : sortOptions.defaultFirst === true;
+    if (shouldSort) {
+      result = this.sortBranches(
+        result,
+        sortOptions.sortBy,
+        sortOptions.sortOrder,
+        sortOptions.defaultFirst
+      );
+    }
+
+    // Step 3: Paginate
+    return this.paginateBranches(result, paginationOptions);
+  }
+
+  /**
+   * Filter branches by name pattern (supports wildcards and regex)
+   */
+  private filterByNamePattern(
+    branches: BranchInfo[],
+    pattern: string,
+    caseInsensitive?: boolean
+  ): BranchInfo[] {
+    // Check if pattern is a regex (enclosed in /)
+    if (pattern.startsWith('/') && pattern.endsWith('/')) {
+      try {
+        const regexPattern = pattern.slice(1, -1);
+        const flags = caseInsensitive ? 'i' : '';
+        const regex = new RegExp(regexPattern, flags);
+        return branches.filter((b) => regex.test(b.displayName));
+      } catch (error) {
+        this.logger.warn('Invalid regex pattern, falling back to no filtering', {
+          pattern,
+          error,
+        });
+        return branches;
+      }
+    }
+
+    // Convert wildcard pattern to regex
+    const regexPattern = pattern
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape special chars
+      .replace(/\*/g, '.*'); // Replace * with .*
+
+    // Handle case sensitivity
+    const flags = caseInsensitive ? 'i' : '';
+
+    try {
+      const regex = new RegExp(`^${regexPattern}$`, flags);
+      return branches.filter((b) => regex.test(b.displayName));
+    } catch (error) {
+      this.logger.warn('Pattern conversion failed, falling back to simple contains', {
+        pattern,
+        error,
+      });
+
+      // Fallback to simple contains check
+      const searchStr = caseInsensitive ? pattern.toLowerCase() : pattern;
+      return branches.filter((b) => {
+        const name = caseInsensitive ? b.displayName.toLowerCase() : b.displayName;
+        return name.includes(searchStr.replace(/\*/g, ''));
+      });
+    }
+  }
+
+  /**
+   * Prioritize branches for intelligent pagination
+   * Orders by: default first, then active by recency, then inactive
+   */
+  private prioritizeBranches(branches: BranchInfo[]): BranchInfo[] {
+    return [...branches].sort((a, b) => {
+      // Default branch always first
+      if (a.isDefault && !b.isDefault) {
+        return -1;
+      }
+      if (!a.isDefault && b.isDefault) {
+        return 1;
+      }
+
+      // Active branches before inactive
+      if (a.isActive && !b.isActive) {
+        return -1;
+      }
+      if (!a.isActive && b.isActive) {
+        return 1;
+      }
+
+      // Within active/inactive groups, sort by last activity
+      const aDate = this.toDate(a.lastActivityDate)?.getTime() ?? 0;
+      const bDate = this.toDate(b.lastActivityDate)?.getTime() ?? 0;
+      return bDate - aDate;
+    });
+  }
+
+  /**
+   * Convert a date string or Date object to Date
+   */
+  private toDate(date: Date | string | undefined): Date | undefined {
+    if (date == null) {
+      return undefined;
+    }
+    if (date instanceof Date) {
+      return date;
+    }
+    const parsed = new Date(date);
+    return isNaN(parsed.getTime()) ? undefined : parsed;
+  }
+}