devops-plugin-kit 0.1.0

package/@danieli-automation/devops-plugin-features/src/features/iterations/api/iterations.ts

@@ -0,0 +1,298 @@
+import { getClient } from "azure-devops-extension-api";
+import { CoreRestClient, TeamContext } from "azure-devops-extension-api/Core";
+import { TeamSettingsIteration } from "azure-devops-extension-api/Work";
+import { witClient, workClient } from "core/azureClients";
+import type { IterationInfoType } from "features/iterations/types/IterationInfoType";
+
+/**
+ * Fetches the list of iterations for a specific project and team.
+ *
+ * Uses the Azure DevOps WorkRestClient to retrieve team iterations and transforms
+ * the response into a more convenient format with ISO date strings.
+ *
+ * @param projectId - The unique identifier of the project
+ * @param teamId - The unique identifier of the team
+ * @returns A promise resolving to an array of IterationInfo objects
+ */
+export async function fetchIterations(projectId: string, teamId: string): Promise<IterationInfoType[]> {
+    // Fetch TEAM iterations first (fast path)
+    let teamIterations: TeamSettingsIteration[] = [];
+    try {
+        // Resolve the correct team context (ids + names) for Work REST calls.
+        const teamContext = await resolveTeamContext(projectId, teamId);
+        // Pull team iterations (usually includes dates + paths).
+        teamIterations = await workClient().getTeamIterations(teamContext);
+    } catch (err) {
+        // If team iterations fail, fall back to the classification tree.
+        console.warn("Failed to fetch team iterations:", { projectId, teamId, err });
+        teamIterations = [];
+    }
+
+    // Normalize/shape team iterations into IterationInfoType and keep only dated entries.
+    const fromTeam = teamIterations
+        .map((iter) => {
+            // Read dates from team iteration attributes.
+            const startRaw = iter.attributes?.startDate;
+            const finishRaw = iter.attributes?.finishDate;
+            // Normalize the path for WIQL compatibility.
+            const finalPath = normalizeIterationPath(String(iter.path ?? iter.name ?? ""));
+
+            return {
+                // Use server id when available; fallback to normalized path for stability.
+                id: String(iter.id ?? finalPath) as any,
+                iterationId: undefined as any,
+                timeFrame: iter.attributes?.timeFrame,
+                name: String(iter.name ?? ""),
+                path: finalPath,
+                // Convert dates to ISO string format.
+                startDate: startRaw ? new Date(startRaw).toISOString() : undefined,
+                finishDate: finishRaw ? new Date(finishRaw).toISOString() : undefined,
+                projectId,
+                teamId,
+            } as IterationInfoType;
+        })
+        .filter((iter) => {
+            // Skip undated iterations (folders or invalid entries).
+            if (!iter.startDate || !iter.finishDate) return false;
+            // Ensure dates parse cleanly.
+            const s = Date.parse(iter.startDate);
+            const f = Date.parse(iter.finishDate);
+            return Number.isFinite(s) && Number.isFinite(f);
+        });
+
+    // If we got valid iterations from the team API, return them.
+    if (fromTeam.length > 0) {
+        return dedupeAndSortIterations(fromTeam);
+    }
+
+    // Fallback: classification tree (slower, but fills gaps)
+    const rootNodes = await witClient().getRootNodes(projectId, 1);
+    // Find the "Iteration" root node.
+    const iterationRoot = rootNodes.find((n: any) => n.structureType === 1);
+    if (!iterationRoot) return [];
+
+    // Fetch the classification nodes (tree of all iterations).
+    let topLevelNodes: any[] = [];
+    try {
+        const fetched = await witClient().getClassificationNodes(projectId, [iterationRoot.id], 100);
+        topLevelNodes = Array.isArray(fetched) ? fetched : [];
+    } catch {
+        const fetched = await witClient().getClassificationNodes(projectId, [iterationRoot.id], 1);
+        topLevelNodes = Array.isArray(fetched) ? fetched : [];
+    }
+
+    // Walk the tree and collect iteration nodes.
+    const iterationNodes: any[] = [];
+    const collect = (node: any) => {
+        if (!node) return;
+        if (node.structureType === 1) iterationNodes.push(node);
+        if (Array.isArray(node.children)) {
+            for (const c of node.children) collect(c);
+        }
+    };
+    for (const n of topLevelNodes) collect(n);
+
+    if (iterationNodes.length === 0) return [];
+
+    // Map classification nodes into IterationInfoType and keep only dated entries.
+    const mapped: IterationInfoType[] = iterationNodes
+        .map((node: any) => {
+            // Normalize the raw node path for WIQL compatibility.
+            const nodePathRaw = String(node.path ?? node.name ?? "");
+            const finalPath = normalizeIterationPath(nodePathRaw);
+            // Read dates from classification node attributes.
+            const startRaw = node.attributes?.startDate;
+            const finishRaw = node.attributes?.finishDate;
+
+            return {
+                // Prefer node identifier/id; fallback to normalized path.
+                id: String(node.identifier ?? node.id ?? finalPath) as any,
+                iterationId: node.id,
+                timeFrame: undefined,
+                name: String(node.name ?? ""),
+                path: finalPath,
+                // Convert dates to ISO string format.
+                startDate: startRaw ? new Date(startRaw).toISOString() : undefined,
+                finishDate: finishRaw ? new Date(finishRaw).toISOString() : undefined,
+                projectId,
+                teamId,
+            } as IterationInfoType;
+        })
+        .filter((iter) => {
+            // Skip undated iterations (folders or invalid entries).
+            if (!iter.startDate || !iter.finishDate) return false;
+            // Ensure dates parse cleanly.
+            const s = Date.parse(iter.startDate);
+            const f = Date.parse(iter.finishDate);
+            return Number.isFinite(s) && Number.isFinite(f);
+        });
+
+    // Deduplicate by canonical path and sort by start date.
+    return dedupeAndSortIterations(mapped);
+}
+
+/**
+ * Fetches team iteration metadata for a project/team pair.
+ *
+ * Uses the Azure DevOps WorkRestClient to retrieve the team's iterations,
+ * normalizes paths, and filters out entries without valid dates.
+ *
+ * @param projectId - The unique identifier of the project
+ * @param teamId - The unique identifier of the team
+ * @returns A promise resolving to an array of IterationInfo objects
+ */
+export async function fetchIterationsPerWorkItem(projectId: string, teamId: string): Promise<IterationInfoType[]> {
+    const teamContext = await resolveTeamContext(projectId, teamId);
+    const teamIterations = await workClient().getTeamIterations(teamContext);
+
+    const teamIterByPath = new Map<string, TeamSettingsIteration>();
+    for (const t of teamIterations) {
+        if (!t?.path) continue;
+        const key = canonicalIterationPath(String(t.path));
+        teamIterByPath.set(key, t);
+    }
+
+    const mapped: IterationInfoType[] = teamIterations
+        .map((node: any) => {
+            const nodePathRaw = String(node.path ?? node.name ?? "");
+            const lookupKey = canonicalIterationPath(nodePathRaw);
+            const teamIteration = teamIterByPath.get(lookupKey);
+            const startRaw = teamIteration?.attributes?.startDate ?? node.attributes?.startDate;
+            const finishRaw = teamIteration?.attributes?.finishDate ?? node.attributes?.finishDate;
+            const finalPath = normalizeIterationPath(String(teamIteration?.path ?? node.path ?? nodePathRaw));
+
+            return {
+                id: node.id,
+                timeFrame: teamIteration?.attributes?.timeFrame,
+                name: node.name,
+                path: finalPath,
+                startDate: startRaw ? new Date(startRaw).toISOString() : undefined,
+                finishDate: finishRaw ? new Date(finishRaw).toISOString() : undefined,
+                projectId,
+                teamId,
+            } as IterationInfoType;
+        })
+        .filter((iter) => {
+            if (!iter.startDate || !iter.finishDate) return false;
+            const s = Date.parse(iter.startDate);
+            const f = Date.parse(iter.finishDate);
+            return Number.isFinite(s) && Number.isFinite(f);
+        });
+    return mapped;
+}
+
+/**
+ * Canonicalizes an iteration path for reliable comparisons and deduplication.
+ *
+ * Normalizes slashes, removes leading separators, and strips the "\Iteration\" segment.
+ *
+ * @param path - Raw iteration path string
+ * @returns Canonicalized iteration path string
+ */
+export function canonicalIterationPath(path: string): string {
+    let p = (path ?? "").trim().toLowerCase();
+
+    // normalize separators
+    p = p.replace(/\//g, "\\");
+
+    // collapse multiple backslashes
+    p = p.replace(/\\\\+/g, "\\");
+
+    // remove ALL leading backslashes
+    p = p.replace(/^\\+/, "");
+
+    // remove ALL trailing backslashes
+    p = p.replace(/\\+$/, "");
+
+    // remove the "\iteration\" segment if present (case-insensitive because we lowercased)
+    p = p.replace(/\\iteration\\/, "\\");
+
+    return p;
+}
+
+/**
+ * Compares two iteration paths for equality after canonical normalization.
+ *
+ * @param a - First iteration path
+ * @param b - Second iteration path
+ * @returns True if canonicalized paths match; otherwise false.
+ */
+export function iterationPathsEqual(a?: string | null, b?: string | null): boolean {
+    return canonicalIterationPath(a ?? "") === canonicalIterationPath(b ?? "");
+}
+
+//#region Private Functions
+/**
+ * Resolves a TeamContext for Work REST calls by looking up project and team names.
+ *
+ * Falls back to provided ids if names are unavailable.
+ *
+ * @param projectId - The unique identifier of the project
+ * @param teamId - The unique identifier of the team
+ * @returns A promise resolving to a TeamContext object
+ */
+async function resolveTeamContext(projectId: string, teamId: string): Promise<TeamContext> {
+    const core = getClient(CoreRestClient);
+
+    const project = await core.getProject(projectId);
+    const team = await core.getTeam(projectId, teamId);
+
+    return {
+        projectId: projectId,
+        teamId: teamId,
+        project: project && project.name ? project.name : projectId,
+        team: team && team.name ? team.name : teamId
+    };
+}
+
+/**
+ * Normalizes an iteration path for WIQL compatibility.
+ *
+ * Collapses duplicate backslashes, removes leading separators,
+ * and strips the "\Iteration\" segment.
+ *
+ * @param path - Raw iteration path string
+ * @returns Normalized iteration path string
+ */
+function normalizeIterationPath(path: string): string {
+    let p = (path ?? "").trim();
+
+    // Convert double slashes to single
+    p = p.replace(/\\\\+/g, "\\");
+
+    // Remove ALL leading backslashes
+    p = p.replace(/^\\+/, "");
+
+    // Some sources include "\Iteration\" explicitly; many queries expect it without that segment.
+    // If your WIQL uses [System.IterationPath] = 'Project\...\Sprint', it should NOT contain "\Iteration\".
+    p = p.replace(/\\Iteration\\/, "\\");
+
+    return p;
+}
+
+/**
+ * Deduplicates iterations by canonical path and sorts them by start date (ascending).
+ *
+ * Uses iteration name as a secondary tie-breaker when dates match.
+ *
+ * @param items - Array of IterationInfo objects
+ * @returns Deduped and sorted array of IterationInfo objects
+ */
+function dedupeAndSortIterations(items: IterationInfoType[]) {
+    const byKey = new Map<string, IterationInfoType>();
+    for (const it of items) {
+        const key = canonicalIterationPath(String(it.path ?? it.name ?? it.id ?? ""));
+        if (!byKey.has(key)) byKey.set(key, it);
+    }
+
+    const unique = Array.from(byKey.values());
+    unique.sort((a, b) => {
+        const aTs = Date.parse(a.startDate ?? "");
+        const bTs = Date.parse(b.startDate ?? "");
+        if (aTs !== bTs) return aTs - bTs;
+        return (a.name ?? "").localeCompare(b.name ?? "");
+    });
+
+    return unique;
+}
+//#endregion

package/@danieli-automation/devops-plugin-features/src/features/iterations/services/IterationService.ts

@@ -0,0 +1,215 @@
+import { fetchIterations } from "features/iterations/api/iterations";
+import { IterationInfoType } from "features/iterations/types/IterationInfoType";
+import { SelectedProjectType } from "features/teams/types/SelectedProjectType";
+import { toIsoDate } from "src/app/utils/date";
+import { extractProjectFromPath } from "src/app/utils/global";
+
+export const IterationService = {
+
+    /**
+    * @description Filters iterations for the current year (Azure DevOps-like),
+    * scoped to the provided project-team pairs.
+    *
+    * It assumes iteration paths contain the year as a folder segment, e.g.:
+    *   "MustafaTeamPath/2026/Sprint 1"
+    *
+    * Rules:
+    * - Only iterations that belong to selected project-team pairs
+    * - Only iterations whose path includes `/<currentYear>/`
+    * - Missing start/finish dates are skipped
+    * - Results are sorted by start date ascending
+    * - Deduplicated by id (fallback to project/team + dates)
+    */
+    getIterationsInScope: (iterations: IterationInfoType[], projectTeamPairs: SelectedProjectType[]): IterationInfoType[] => {
+
+        const year = new Date().getFullYear();
+        const yearSegment = `\\${year}\\`;
+
+        const inCurrentYearFolder = (iter: IterationInfoType) => typeof iter.path === "string" && iter.path.includes(yearSegment);
+        const belongsToSelectedPair = (iter: IterationInfoType) => projectTeamPairs.some(p => p.projectId === iter.projectId && p.teamId === iter.teamId);
+
+        const filtered = iterations.filter(iter => {
+            if (!iter.startDate || !iter.finishDate) return false;
+            if (!belongsToSelectedPair(iter)) return false;
+            if (!inCurrentYearFolder(iter)) return false;
+            return true;
+        });
+
+        filtered.sort((a, b) => Date.parse(a.startDate!) - Date.parse(b.startDate!));
+
+        // Deduplicate
+        const seen = new Set<string>();
+        const deduped: IterationInfoType[] = [];
+        for (const it of filtered) {
+            const key = (it.id ? String(it.id) : `${it.projectId}:${it.teamId}:${it.startDate}:${it.finishDate}`) + `@${it.projectId}:${it.teamId}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                deduped.push(it);
+            }
+        }
+
+        return deduped;
+    },
+
+
+    /**
+     * Gets allowed iteration paths for the selected project-team pairs based on the chosen iteration group's dates.
+     * 
+     * Uses fetchIterations to retrieve iterations for each project-team pair, then filters them to find those
+     * that match the start and finish dates of the chosen iteration group.
+     * 
+     * @param selectedProjectPairs - Array of selected project and team ID pairs
+     * @param chosenIterationGroup  - The iteration group with startDate and finishDate to match against
+     * @returns A promise resolving to an array of allowed iteration paths
+     */
+    getAllowedIterationPathsForSelection: async (selectedProjectPairs: SelectedProjectType[], chosenIterationGroup: { startDate: string; finishDate: string }): Promise<string[]> => {
+        if (!Array.isArray(selectedProjectPairs) || selectedProjectPairs.length === 0) return [];
+
+        const { startDate: chosenStartRaw, finishDate: chosenFinishRaw } = chosenIterationGroup || {};
+
+        const results = await Promise.all(
+            selectedProjectPairs.map(p => fetchIterations(p.projectId, p.teamId))
+        );
+
+        if (!chosenStartRaw || !chosenFinishRaw) return [];
+        const chosenStart = Date.parse(chosenStartRaw);
+        const chosenFinish = Date.parse(chosenFinishRaw);
+        const allIterations = results.flat().filter(Boolean);
+
+        // pick only iterations whose start/finish match chosenIterationGroup
+        const allowed = allIterations
+            .filter(iter => iter && iter.startDate && iter.finishDate)
+            .filter(iter => {
+                const s = Date.parse(iter.startDate!);
+                const f = Date.parse(iter.finishDate!);
+
+                // skip invalid iteration dates
+                if (isNaN(s) || isNaN(f)) return false;
+
+                return s === chosenStart && f === chosenFinish;
+            })
+            .map(iter => iter.path);
+
+        return Array.from(new Set(allowed));
+    },
+
+    /**
+     * Filters a list of iterations to include only future iterations
+     * starting from the **first day of the next month** up to the **end of the current year**.
+     *
+     * The lower bound is calculated as **00:00 (local time)** on the **1st day of the next month**.
+     * The upper bound is calculated as **23:59:59.999 (local time)** on **December 31st of the current year**.
+     *
+     * An iteration is included if its **startDate** falls within this time window.
+     *
+     * Invalid iterations are excluded:
+     * - Missing startDate or finishDate
+     * - Unparseable dates (Date.parse returns NaN)
+     * - The current iteration (if provided), matched by id
+     *
+     * @param iterations - Array of iterations to filter
+     * @param currentIteration - The currently active iteration to exclude from the results (optional)
+     * @returns A filtered array containing future iterations from next month until the end of the year
+     */
+    filterFutureIterations: (iterations: IterationInfoType[], currentIteration: IterationInfoType | undefined | null) => {
+        const now = new Date();
+
+        // Start at 00:00 on the 1st day of NEXT month (local time)
+        const startOfNextMonth = new Date(now.getFullYear(), now.getMonth() + 1, 1).getTime();
+
+        // End at 23:59:59.999 on Dec 31 of THIS year (local time)
+        const endOfYear = new Date(now.getFullYear(), 11, 31, 23, 59, 59, 999).getTime();
+
+        return iterations.filter(({ id, startDate, finishDate }) => {
+            if (!startDate || !finishDate) return false;
+
+            const start = Date.parse(startDate);
+            const end = Date.parse(finishDate);
+            if (Number.isNaN(start) || Number.isNaN(end)) return false;
+
+            // exclude current iteration (if provided)
+            if (currentIteration?.id != null && String(currentIteration.id) === String(id)) return false;
+
+            // include iterations that START between next month start and end of year
+            return start >= startOfNextMonth && start <= endOfYear;
+        });
+    },
+
+    /**
+     * Groups iterations by their start and end dates.
+     * Iterations with the same start and end dates are combined into a single entry,
+     * with their paths and included projects aggregated.
+     * 
+     * @param iterations Array of IterationInfoType objects
+     * @returns Array of grouped IterationInfoType objects
+     */
+    groupIterationsByStartEnd: (iterations: IterationInfoType[]): IterationInfoType[] => {
+        const map = new Map<string, IterationInfoType>();
+
+        for (const iter of iterations) {
+            const projectFromPath = extractProjectFromPath(iter.path);
+
+            if (iter.startDate && iter.finishDate) {
+                const startDate = toIsoDate(iter.startDate);
+                const finishDate = toIsoDate(iter.finishDate);
+                const key = `DATED__${startDate}__${finishDate}`;
+
+                const existing = map.get(key);
+                if (!existing) {
+                    map.set(key, {
+                        ...iter,
+                        startDate,
+                        finishDate,
+                        paths: [iter.path],
+                        projectsIncludedInIteration: [projectFromPath],
+                    });
+                } else {
+                    existing.paths = Array.from(new Set([...(existing.paths ?? []), iter.path]));
+                    existing.projectsIncludedInIteration = Array.from(
+                        new Set([...(existing.projectsIncludedInIteration ?? []), projectFromPath])
+                    );
+                }
+
+                continue;
+            }
+
+            const key = `UNDATED__${iter.path}`;
+
+            const existing = map.get(key);
+            if (!existing) {
+                map.set(key, {
+                    ...iter,
+                    paths: [iter.path],
+                    projectsIncludedInIteration: [projectFromPath],
+                });
+            } else {
+                existing.paths = Array.from(new Set([...(existing.paths ?? []), iter.path]));
+                existing.projectsIncludedInIteration = Array.from(
+                    new Set([...(existing.projectsIncludedInIteration ?? []), projectFromPath])
+                );
+            }
+        }
+
+        return Array.from(map.values()).sort((a, b) => {
+
+            const aHas = a.startDate && a.finishDate;
+            const bHas = b.startDate && b.finishDate;
+            if (aHas && !bHas) return -1;
+            if (!aHas && bHas) return 1;
+
+            if (aHas && bHas) return String(a.startDate).localeCompare(String(b.startDate));
+
+            return String(a.path).localeCompare(String(b.path));
+        });
+    },
+
+    /**
+     * Gets iteration paths from an array of iterations.
+     * 
+     * @param iterations Array of IterationInfoType objects
+     * @returns Array of iteration paths as strings
+     */
+    getIterationPaths: (iterations: IterationInfoType[]): string[] => {
+        return iterations.map(iter => iter.path);
+    }
+};

package/@danieli-automation/devops-plugin-features/src/features/iterations/types/IterationInfoType.ts

@@ -0,0 +1,15 @@
+export type IterationInfoType = {
+    id: string;
+    iterationId?: number;
+    name: string;
+    path: string;
+    startDate?: string;
+    finishDate?: string;
+    projectId: string;
+    teamId: string;
+    paths?: string[];
+    timeFrame?: number;
+    level1?: string;
+    level2?: string;
+    projectsIncludedInIteration?: string[];
+};

package/@danieli-automation/devops-plugin-features/src/features/iterations/utils/__tests__/iteration.test.ts

@@ -0,0 +1,39 @@
+import type { IterationInfoType } from "features/iterations/types/IterationInfoType";
+import { describe, expect, it } from "vitest";
+import { formatIteration } from "../iteration.js";
+
+describe("Utils: Iteration Helper Tests: ", () => {
+
+    //#region formatIteration
+    it("formatIteration: returns formatted iteration in specified format if there is any provided iteration", () => {
+
+        const iteration: IterationInfoType = {
+            id: "1",
+            name: "Iteration Name",
+            path: "Iteration Path",
+            startDate: "2026-01-15T00:00:00.000Z",
+            finishDate: "2026-01-31T23:59:00.000Z",
+            projectId: "ProjectId",
+            teamId: "TeamId"
+        }
+
+        expect(formatIteration(iteration)).toBe("2026 Jan (15-31)");
+    });
+
+    it("formatIteration: returns empty string if startDate is invalid", () => {
+
+        const iteration: IterationInfoType = {
+            id: "1",
+            name: "Iteration Name",
+            path: "Iteration Path",
+            startDate: "2026-01-15",
+            finishDate: "not-a-date",
+            projectId: "ProjectId",
+            teamId: "TeamId",
+        };
+
+        expect(formatIteration(iteration as any)).toBe("");
+    });
+
+    //#endregion
+})