specweave 0.14.0 → 0.15.0

package/plugins/specweave-ado/lib/ado-hierarchical-sync.js

@@ -1,49 +1,72 @@
-import {
-  isSimpleStrategy,
-  isFilteredStrategy,
-  isCustomStrategy
-} from "../../../src/core/types/sync-profile.js";
-import { getAreaPaths } from "./ado-board-resolver.js";
-import https from "https";
-async function buildHierarchicalWIQL(organization, pat, containers) {
-  const projectClauses = [];
-  for (const container of containers) {
-    const parts = [];
-    parts.push(`[System.TeamProject] = '${container.id}'`);
-    if (container.subOrganizations && container.subOrganizations.length > 0) {
-      try {
-        const areaPaths = await getAreaPaths(
-          organization,
-          container.id,
-          pat,
-          container.subOrganizations
-        );
-        if (areaPaths.length > 0) {
-          const areaPathClauses = areaPaths.map((path) => `[System.AreaPath] UNDER '${path}'`).join(" OR ");
-          parts.push(`(${areaPathClauses})`);
-        } else {
-          console.warn(
-            `\u26A0\uFE0F  No valid area paths found for project ${container.id}, syncing all areas`
-          );
+/**
+ * Azure DevOps Hierarchical Sync Implementation
+ *
+ * Supports three sync strategies:
+ * 1. Simple: One project, all work items (backward compatible)
+ * 2. Filtered: Multiple projects + area paths + filters
+ * 3. Custom: Raw WIQL query
+ */
+import { isSimpleStrategy, isFilteredStrategy, isCustomStrategy, } from '../../../src/core/types/sync-profile.js';
+import { getAreaPaths } from './ado-board-resolver.js';
+import https from 'https';
+/**
+ * Build hierarchical WIQL query from containers
+ *
+ * Example output:
+ * SELECT [System.Id], [System.Title], [System.State]
+ * FROM WorkItems
+ * WHERE (
+ *   ([System.TeamProject] = 'PROJECT-A' AND [System.AreaPath] UNDER 'PROJECT-A\\Team Alpha')
+ *   OR
+ *   ([System.TeamProject] = 'PROJECT-B' AND [System.AreaPath] UNDER 'PROJECT-B\\Platform')
+ * )
+ * AND [System.WorkItemType] IN ('User Story', 'Bug')
+ * AND [System.State] IN ('Active', 'New')
+ *
+ * @param organization Organization name
+ * @param pat Personal Access Token
+ * @param containers Array of containers (projects) with filters
+ * @returns WIQL query string
+ */
+export async function buildHierarchicalWIQL(organization, pat, containers) {
+    const projectClauses = [];
+    for (const container of containers) {
+        const parts = [];
+        // Project clause
+        parts.push(`[System.TeamProject] = '${container.id}'`);
+        // Area path filtering (sub-organizations)
+        if (container.subOrganizations && container.subOrganizations.length > 0) {
+            try {
+                const areaPaths = await getAreaPaths(organization, container.id, pat, container.subOrganizations);
+                if (areaPaths.length > 0) {
+                    const areaPathClauses = areaPaths
+                        .map((path) => `[System.AreaPath] UNDER '${path}'`)
+                        .join(' OR ');
+                    parts.push(`(${areaPathClauses})`);
+                }
+                else {
+                    console.warn(`⚠️  No valid area paths found for project ${container.id}, syncing all areas`);
+                }
+            }
+            catch (error) {
+                console.warn(`⚠️  Failed to resolve area paths for ${container.id}, syncing all areas:`, error.message);
+            }
         }
-      } catch (error) {
-        console.warn(
-          `\u26A0\uFE0F  Failed to resolve area paths for ${container.id}, syncing all areas:`,
-          error.message
-        );
-      }
+        // Combine parts with AND
+        projectClauses.push(`(${parts.join(' AND ')})`);
     }
-    projectClauses.push(`(${parts.join(" AND ")})`);
-  }
-  let whereClause = projectClauses.join(" OR ");
-  const filters = containers[0]?.filters;
-  if (filters) {
-    const filterClauses = buildFilterClauses(filters);
-    if (filterClauses.length > 0) {
-      whereClause = `(${whereClause}) AND ${filterClauses.join(" AND ")}`;
+    // Build WHERE clause with project clauses
+    let whereClause = projectClauses.join(' OR ');
+    // Add global filters (apply to all projects)
+    const filters = containers[0]?.filters;
+    if (filters) {
+        const filterClauses = buildFilterClauses(filters);
+        if (filterClauses.length > 0) {
+            whereClause = `(${whereClause}) AND ${filterClauses.join(' AND ')}`;
+        }
     }
-  }
-  return `
+    // Build complete WIQL query
+    return `
     SELECT [System.Id], [System.Title], [System.Description], [System.State],
            [System.CreatedDate], [System.ChangedDate], [System.WorkItemType],
            [System.AreaPath], [System.IterationPath], [System.Tags]
@@ -52,207 +75,296 @@ async function buildHierarchicalWIQL(organization, pat, containers) {
     ORDER BY [System.CreatedDate] DESC
   `.trim();
 }
+/**
+ * Build filter clauses from container filters
+ *
+ * @param filters Container filters
+ * @returns Array of WIQL filter clauses
+ */
 function buildFilterClauses(filters) {
-  const clauses = [];
-  if (filters.workItemTypes && filters.workItemTypes.length > 0) {
-    const types = filters.workItemTypes.map((t) => `'${t}'`).join(", ");
-    clauses.push(`[System.WorkItemType] IN (${types})`);
-  }
-  if (filters.statusCategories && filters.statusCategories.length > 0) {
-    const states = filters.statusCategories.map((s) => `'${s}'`).join(", ");
-    clauses.push(`[System.State] IN (${states})`);
-  }
-  if (filters.areaPaths && filters.areaPaths.length > 0) {
-    const areaPathClauses = filters.areaPaths.map((path) => `[System.AreaPath] UNDER '${path}'`).join(" OR ");
-    clauses.push(`(${areaPathClauses})`);
-  }
-  if (filters.iterationPaths && filters.iterationPaths.length > 0) {
-    const iterationClauses = filters.iterationPaths.map((path) => `[System.IterationPath] UNDER '${path}'`).join(" OR ");
-    clauses.push(`(${iterationClauses})`);
-  }
-  if (filters.includeLabels && filters.includeLabels.length > 0) {
-    const tagClauses = filters.includeLabels.map((tag) => `[System.Tags] CONTAINS '${tag}'`).join(" OR ");
-    clauses.push(`(${tagClauses})`);
-  }
-  if (filters.excludeLabels && filters.excludeLabels.length > 0) {
-    for (const tag of filters.excludeLabels) {
-      clauses.push(`NOT [System.Tags] CONTAINS '${tag}'`);
+    const clauses = [];
+    // Work item types (ADO-specific)
+    if (filters.workItemTypes && filters.workItemTypes.length > 0) {
+        const types = filters.workItemTypes.map((t) => `'${t}'`).join(', ');
+        clauses.push(`[System.WorkItemType] IN (${types})`);
+    }
+    // Status categories (ADO uses State field)
+    if (filters.statusCategories && filters.statusCategories.length > 0) {
+        const states = filters.statusCategories.map((s) => `'${s}'`).join(', ');
+        clauses.push(`[System.State] IN (${states})`);
+    }
+    // Area paths (additional filtering beyond sub-organizations)
+    if (filters.areaPaths && filters.areaPaths.length > 0) {
+        const areaPathClauses = filters.areaPaths
+            .map((path) => `[System.AreaPath] UNDER '${path}'`)
+            .join(' OR ');
+        clauses.push(`(${areaPathClauses})`);
+    }
+    // Iteration paths (sprints in ADO)
+    if (filters.iterationPaths && filters.iterationPaths.length > 0) {
+        const iterationClauses = filters.iterationPaths
+            .map((path) => `[System.IterationPath] UNDER '${path}'`)
+            .join(' OR ');
+        clauses.push(`(${iterationClauses})`);
+    }
+    // Tags (labels in ADO)
+    if (filters.includeLabels && filters.includeLabels.length > 0) {
+        const tagClauses = filters.includeLabels
+            .map((tag) => `[System.Tags] CONTAINS '${tag}'`)
+            .join(' OR ');
+        clauses.push(`(${tagClauses})`);
+    }
+    // Exclude labels/tags
+    if (filters.excludeLabels && filters.excludeLabels.length > 0) {
+        for (const tag of filters.excludeLabels) {
+            clauses.push(`NOT [System.Tags] CONTAINS '${tag}'`);
+        }
     }
-  }
-  if (filters.assignees && filters.assignees.length > 0) {
-    const assigneeClauses = filters.assignees.map((assignee) => `[System.AssignedTo] = '${assignee}'`).join(" OR ");
-    clauses.push(`(${assigneeClauses})`);
-  }
-  return clauses;
+    // Assignees (assigned to)
+    if (filters.assignees && filters.assignees.length > 0) {
+        const assigneeClauses = filters.assignees
+            .map((assignee) => `[System.AssignedTo] = '${assignee}'`)
+            .join(' OR ');
+        clauses.push(`(${assigneeClauses})`);
+    }
+    return clauses;
 }
+/**
+ * Add time range filter to WIQL query
+ *
+ * @param wiql Base WIQL query
+ * @param timeRange Time range preset (1W, 1M, 3M, 6M, ALL)
+ * @returns WIQL with time range filter
+ */
 function addTimeRangeFilter(wiql, timeRange) {
-  if (timeRange === "ALL") {
-    return wiql;
-  }
-  const { since, until } = calculateTimeRange(timeRange);
-  const timeFilter = `[System.CreatedDate] >= '${since}' AND [System.CreatedDate] <= '${until}'`;
-  if (wiql.includes("ORDER BY")) {
-    return wiql.replace("ORDER BY", `AND ${timeFilter} ORDER BY`);
-  } else {
-    return `${wiql} AND ${timeFilter}`;
-  }
+    if (timeRange === 'ALL') {
+        return wiql; // No time filter
+    }
+    const { since, until } = calculateTimeRange(timeRange);
+    // Add time range to WHERE clause
+    const timeFilter = `[System.CreatedDate] >= '${since}' AND [System.CreatedDate] <= '${until}'`;
+    // Insert before ORDER BY if present, otherwise append
+    if (wiql.includes('ORDER BY')) {
+        return wiql.replace('ORDER BY', `AND ${timeFilter} ORDER BY`);
+    }
+    else {
+        return `${wiql} AND ${timeFilter}`;
+    }
 }
+/**
+ * Calculate date range from time range preset
+ */
 function calculateTimeRange(timeRange) {
-  const now = /* @__PURE__ */ new Date();
-  const since = new Date(now);
-  switch (timeRange) {
-    case "1W":
-      since.setDate(now.getDate() - 7);
-      break;
-    case "2W":
-      since.setDate(now.getDate() - 14);
-      break;
-    case "1M":
-      since.setMonth(now.getMonth() - 1);
-      break;
-    case "3M":
-      since.setMonth(now.getMonth() - 3);
-      break;
-    case "6M":
-      since.setMonth(now.getMonth() - 6);
-      break;
-    case "1Y":
-      since.setFullYear(now.getFullYear() - 1);
-      break;
-    case "ALL":
-      return {
-        since: "1970-01-01T00:00:00Z",
-        until: now.toISOString()
-      };
-  }
-  return {
-    since: since.toISOString(),
-    until: now.toISOString()
-  };
+    const now = new Date();
+    const since = new Date(now);
+    switch (timeRange) {
+        case '1W':
+            since.setDate(now.getDate() - 7);
+            break;
+        case '2W':
+            since.setDate(now.getDate() - 14);
+            break;
+        case '1M':
+            since.setMonth(now.getMonth() - 1);
+            break;
+        case '3M':
+            since.setMonth(now.getMonth() - 3);
+            break;
+        case '6M':
+            since.setMonth(now.getMonth() - 6);
+            break;
+        case '1Y':
+            since.setFullYear(now.getFullYear() - 1);
+            break;
+        case 'ALL':
+            return {
+                since: '1970-01-01T00:00:00Z',
+                until: now.toISOString(),
+            };
+    }
+    return {
+        since: since.toISOString(),
+        until: now.toISOString(),
+    };
 }
-async function fetchWorkItemsHierarchical(profile, pat, timeRange = "1M") {
-  const config = profile.config;
-  if (isSimpleStrategy(profile)) {
+/**
+ * Fetch work items hierarchically based on sync strategy
+ *
+ * @param profile Sync profile with strategy
+ * @param pat Personal Access Token
+ * @param timeRange Time range preset
+ * @returns Array of work items
+ */
+export async function fetchWorkItemsHierarchical(profile, pat, timeRange = '1M') {
+    const config = profile.config;
+    // Strategy 1: SIMPLE (backward compatible)
+    if (isSimpleStrategy(profile)) {
+        return fetchWorkItemsSimple(config, pat, timeRange);
+    }
+    // Strategy 2: CUSTOM (raw WIQL)
+    if (isCustomStrategy(profile)) {
+        return fetchWorkItemsCustom(config, pat, timeRange);
+    }
+    // Strategy 3: FILTERED (hierarchical)
+    if (isFilteredStrategy(profile)) {
+        return fetchWorkItemsFiltered(config, pat, timeRange);
+    }
+    // Default to simple if strategy not recognized
+    console.warn('⚠️  Unknown strategy, defaulting to simple');
     return fetchWorkItemsSimple(config, pat, timeRange);
-  }
-  if (isCustomStrategy(profile)) {
-    return fetchWorkItemsCustom(config, pat, timeRange);
-  }
-  if (isFilteredStrategy(profile)) {
-    return fetchWorkItemsFiltered(config, pat, timeRange);
-  }
-  console.warn("\u26A0\uFE0F  Unknown strategy, defaulting to simple");
-  return fetchWorkItemsSimple(config, pat, timeRange);
 }
+/**
+ * Fetch work items using SIMPLE strategy (one project, all work items)
+ *
+ * @param config ADO configuration
+ * @param pat Personal Access Token
+ * @param timeRange Time range preset
+ * @returns Array of work items
+ */
 async function fetchWorkItemsSimple(config, pat, timeRange) {
-  const organization = config.organization;
-  const project = config.project;
-  if (!project) {
-    throw new Error("Simple strategy requires project in config");
-  }
-  let wiql = `
+    const organization = config.organization;
+    const project = config.project;
+    if (!project) {
+        throw new Error('Simple strategy requires project in config');
+    }
+    let wiql = `
     SELECT [System.Id], [System.Title], [System.State], [System.CreatedDate]
     FROM WorkItems
     WHERE [System.TeamProject] = '${project}'
   `.trim();
-  wiql = addTimeRangeFilter(wiql, timeRange);
-  console.log("\u{1F50D} Fetching work items (SIMPLE strategy):", wiql);
-  return executeQuery(organization, project, pat, wiql);
+    // Add time range
+    wiql = addTimeRangeFilter(wiql, timeRange);
+    console.log('🔍 Fetching work items (SIMPLE strategy):', wiql);
+    return executeQuery(organization, project, pat, wiql);
 }
+/**
+ * Fetch work items using CUSTOM strategy (raw WIQL)
+ *
+ * @param config ADO configuration
+ * @param pat Personal Access Token
+ * @param timeRange Time range preset
+ * @returns Array of work items
+ */
 async function fetchWorkItemsCustom(config, pat, timeRange) {
-  const organization = config.organization;
-  const project = config.project || "DefaultProject";
-  const customQuery = config.customQuery;
-  if (!customQuery) {
-    throw new Error("Custom strategy requires customQuery in config");
-  }
-  const wiql = addTimeRangeFilter(customQuery, timeRange);
-  console.log("\u{1F50D} Fetching work items (CUSTOM strategy):", wiql);
-  return executeQuery(organization, project, pat, wiql);
+    const organization = config.organization;
+    const project = config.project || 'DefaultProject';
+    const customQuery = config.customQuery;
+    if (!customQuery) {
+        throw new Error('Custom strategy requires customQuery in config');
+    }
+    // Add time range to custom query
+    const wiql = addTimeRangeFilter(customQuery, timeRange);
+    console.log('🔍 Fetching work items (CUSTOM strategy):', wiql);
+    return executeQuery(organization, project, pat, wiql);
 }
+/**
+ * Fetch work items using FILTERED strategy (multiple projects + area paths + filters)
+ *
+ * @param config ADO configuration
+ * @param pat Personal Access Token
+ * @param timeRange Time range preset
+ * @returns Array of work items
+ */
 async function fetchWorkItemsFiltered(config, pat, timeRange) {
-  const organization = config.organization;
-  const containers = config.containers;
-  if (!containers || containers.length === 0) {
-    throw new Error("Filtered strategy requires containers array in config");
-  }
-  const baseWiql = await buildHierarchicalWIQL(organization, pat, containers);
-  const wiql = addTimeRangeFilter(baseWiql, timeRange);
-  console.log("\u{1F50D} Fetching work items (FILTERED strategy):", wiql);
-  const project = containers[0].id;
-  return executeQuery(organization, project, pat, wiql);
+    const organization = config.organization;
+    const containers = config.containers;
+    if (!containers || containers.length === 0) {
+        throw new Error('Filtered strategy requires containers array in config');
+    }
+    // Build hierarchical WIQL
+    const baseWiql = await buildHierarchicalWIQL(organization, pat, containers);
+    // Add time range
+    const wiql = addTimeRangeFilter(baseWiql, timeRange);
+    console.log('🔍 Fetching work items (FILTERED strategy):', wiql);
+    // Use first project for API endpoint (WIQL can query across projects)
+    const project = containers[0].id;
+    return executeQuery(organization, project, pat, wiql);
 }
+/**
+ * Execute WIQL query and return work items
+ *
+ * @param organization Organization name
+ * @param project Project name
+ * @param pat Personal Access Token
+ * @param wiql WIQL query string
+ * @returns Array of work items
+ */
 async function executeQuery(organization, project, pat, wiql) {
-  const baseUrl = `https://dev.azure.com/${organization}/${project}`;
-  const queryUrl = `${baseUrl}/_apis/wit/wiql?api-version=7.1`;
-  const queryResult = await makeRequest(queryUrl, pat, "POST", { query: wiql });
-  if (!queryResult.workItems || queryResult.workItems.length === 0) {
-    return [];
-  }
-  const ids = queryResult.workItems.map((wi) => wi.id);
-  const batchUrl = `${baseUrl}/_apis/wit/workitemsbatch?api-version=7.1`;
-  const response = await makeRequest(batchUrl, pat, "POST", {
-    ids,
-    fields: [
-      "System.Id",
-      "System.Title",
-      "System.Description",
-      "System.State",
-      "System.CreatedDate",
-      "System.ChangedDate",
-      "System.WorkItemType",
-      "System.AreaPath",
-      "System.IterationPath",
-      "System.Tags"
-    ]
-  });
-  return response.value || [];
-}
-function makeRequest(url, pat, method = "GET", body) {
-  return new Promise((resolve, reject) => {
-    const { hostname, pathname, search } = new URL(url);
-    const authHeader = "Basic " + Buffer.from(`:${pat}`).toString("base64");
-    const headers = {
-      Authorization: authHeader,
-      Accept: "application/json"
-    };
-    if (body) {
-      headers["Content-Type"] = "application/json";
+    const baseUrl = `https://dev.azure.com/${organization}/${project}`;
+    // Execute query
+    const queryUrl = `${baseUrl}/_apis/wit/wiql?api-version=7.1`;
+    const queryResult = await makeRequest(queryUrl, pat, 'POST', { query: wiql });
+    if (!queryResult.workItems || queryResult.workItems.length === 0) {
+        return [];
     }
-    const options = {
-      hostname,
-      path: pathname + search,
-      method,
-      headers
-    };
-    const req = https.request(options, (res) => {
-      let data = "";
-      res.on("data", (chunk) => {
-        data += chunk;
-      });
-      res.on("end", () => {
-        try {
-          const parsed = JSON.parse(data);
-          if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
-            resolve(parsed);
-          } else {
-            reject(new Error(`HTTP ${res.statusCode}: ${parsed.message || data}`));
-          }
-        } catch (error) {
-          reject(new Error(`Failed to parse response: ${data}`));
-        }
-      });
+    // Get full work item details (batch request)
+    const ids = queryResult.workItems.map((wi) => wi.id);
+    const batchUrl = `${baseUrl}/_apis/wit/workitemsbatch?api-version=7.1`;
+    const response = await makeRequest(batchUrl, pat, 'POST', {
+        ids,
+        fields: [
+            'System.Id',
+            'System.Title',
+            'System.Description',
+            'System.State',
+            'System.CreatedDate',
+            'System.ChangedDate',
+            'System.WorkItemType',
+            'System.AreaPath',
+            'System.IterationPath',
+            'System.Tags',
+        ],
     });
-    req.on("error", (error) => {
-      reject(error);
+    return response.value || [];
+}
+/**
+ * Make HTTPS request to ADO API
+ */
+function makeRequest(url, pat, method = 'GET', body) {
+    return new Promise((resolve, reject) => {
+        const { hostname, pathname, search } = new URL(url);
+        const authHeader = 'Basic ' + Buffer.from(`:${pat}`).toString('base64');
+        const headers = {
+            Authorization: authHeader,
+            Accept: 'application/json',
+        };
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const options = {
+            hostname,
+            path: pathname + search,
+            method,
+            headers,
+        };
+        const req = https.request(options, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    const parsed = JSON.parse(data);
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        resolve(parsed);
+                    }
+                    else {
+                        reject(new Error(`HTTP ${res.statusCode}: ${parsed.message || data}`));
+                    }
+                }
+                catch (error) {
+                    reject(new Error(`Failed to parse response: ${data}`));
+                }
+            });
+        });
+        req.on('error', (error) => {
+            reject(error);
+        });
+        // Send body if present
+        if (body) {
+            req.write(JSON.stringify(body));
+        }
+        req.end();
     });
-    if (body) {
-      req.write(JSON.stringify(body));
-    }
-    req.end();
-  });
 }
-export {
-  buildHierarchicalWIQL,
-  fetchWorkItemsHierarchical
-};
+//# sourceMappingURL=ado-hierarchical-sync.js.map