@elisra-devops/docgen-data-provider 1.105.0 → 1.107.0

package/bin/modules/TicketsDataProvider.js

@@ -10,6 +10,24 @@ const tfs_data_5 = require("../models/tfs-data");
 const tfs_data_6 = require("../models/tfs-data");
 const logger_1 = require("../utils/logger");
 const pLimit = require('p-limit');
+const HISTORICAL_WIT_API_VERSIONS = ['7.1', '5.1', null];
+const HISTORICAL_BATCH_MAX_IDS = 200;
+const HISTORICAL_WORK_ITEM_FIELDS = [
+    'System.Id',
+    'System.WorkItemType',
+    'System.Title',
+    'System.State',
+    'System.AreaPath',
+    'System.IterationPath',
+    'System.Rev',
+    'System.ChangedDate',
+    'System.Description',
+    'Microsoft.VSTS.TCM.Steps',
+    'Elisra.TestPhase',
+    'Custom.TestPhase',
+];
+/** Default fields fetched per work item in tree/flat query parsing. */
+const WI_DEFAULT_FIELDS = 'System.Description,System.Title,Microsoft.VSTS.TCM.ReproSteps,Microsoft.VSTS.CMMI.Symptom';
 class TicketsDataProvider {
     constructor(orgUrl, token) {
         this.orgUrl = '';
@@ -163,14 +181,24 @@ class TicketsDataProvider {
      * @param docType document type
      * @returns
      */
+    normalizeSharedQueriesPath(path) {
+        const raw = String(path || '').trim();
+        if (!raw)
+            return '';
+        const normalized = raw.toLowerCase();
+        if (normalized === 'shared' || normalized === 'shared queries')
+            return '';
+        return raw;
+    }
     async GetSharedQueries(project, path, docType = '') {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
         let url;
         try {
-            if (path === '')
+            const normalizedPath = this.normalizeSharedQueriesPath(path);
+            if (normalizedPath === '')
                 url = `${this.orgUrl}${project}/_apis/wit/queries/Shared%20Queries?$depth=2&$expand=all`;
             else
-                url = `${this.orgUrl}${project}/_apis/wit/queries/${path}?$depth=2&$expand=all`;
+                url = `${this.orgUrl}${project}/_apis/wit/queries/${normalizedPath}?$depth=2&$expand=all`;
             let queries = await tfs_1.TFSServices.getItemContent(url, this.token);
             logger_1.default.debug(`doctype: ${docType}`);
             const normalizedDocType = (docType || '').toLowerCase();
@@ -310,6 +338,8 @@ class TicketsDataProvider {
                 }
                 case 'srs':
                     return await this.fetchSrsQueries(queriesWithChildren);
+                case 'sysrs':
+                    return await this.fetchSysRsQueries(queriesWithChildren);
                 case 'svd': {
                     const { root: svdRoot, found } = await this.getDocTypeRoot(queriesWithChildren, 'svd');
                     if (!found) {
@@ -344,6 +374,13 @@ class TicketsDataProvider {
                         knownBugsQueryTree: (_y = knownBugsFetch === null || knownBugsFetch === void 0 ? void 0 : knownBugsFetch.result) !== null && _y !== void 0 ? _y : null,
                     };
                 }
+                case 'historical-query':
+                case 'historical': {
+                    const { tree1 } = await this.structureAllQueryPath(queriesWithChildren);
+                    return {
+                        historicalQueryTree: tree1 ? [tree1] : [],
+                    };
+                }
                 default:
                     break;
             }
@@ -513,6 +550,33 @@ class TicketsDataProvider {
             softwareToSystemRequirementsQueries,
         };
     }
+    async fetchSysRsQueries(rootQueries) {
+        const { root: sysRsRoot, found: sysRsRootFound } = await this.getDocTypeRoot(rootQueries, 'sysrs');
+        logger_1.default.debug(`[GetSharedQueries][sysrs] using ${sysRsRootFound ? 'dedicated folder' : 'root queries'}`);
+        const systemRequirementsQueries = await this.fetchSystemRequirementQueries(sysRsRoot, [
+            'System To Customer',
+            'System To Subsystem',
+        ]);
+        const systemToCustomerFolder = await this.findChildFolderByPossibleNames(sysRsRoot, [
+            'system to customer',
+            'system-to-customer',
+            'system customer',
+            'subsystem to system',
+            'customer to system',
+        ]);
+        const systemToSubsystemFolder = await this.findChildFolderByPossibleNames(sysRsRoot, [
+            'system to subsystem',
+            'system-to-subsystem',
+            'system subsystem',
+        ]);
+        const subsystemToSystemRequirementsQueries = await this.fetchRequirementsTraceQueriesForFolder(systemToCustomerFolder);
+        const systemToSubsystemRequirementsQueries = await this.fetchRequirementsTraceQueriesForFolder(systemToSubsystemFolder);
+        return {
+            systemRequirementsQueries,
+            subsystemToSystemRequirementsQueries,
+            systemToSubsystemRequirementsQueries,
+        };
+    }
     /**
      * Fetches and structures linked queries related to requirements traceability with area path filtering.
      *
@@ -530,8 +594,7 @@ class TicketsDataProvider {
      */
     async fetchLinkedRequirementsTraceQueries(queries, onlySourceSide = false) {
         const { tree1: SystemToSoftwareRequirementsTree, tree2: SoftwareToSystemRequirementsTree } = await this.structureFetchedQueries(queries, onlySourceSide, null, ['epic', 'feature', 'requirement'], ['epic', 'feature', 'requirement'], 'sys', // Source area filter for tree1: System area paths
-        'soft' // Target area filter for tree1: Software area paths (tree2 will be reversed automatically)
-        );
+        'soft');
         return { SystemToSoftwareRequirementsTree, SoftwareToSystemRequirementsTree };
     }
     async fetchRequirementsTraceQueriesForFolder(folder) {
@@ -802,7 +865,7 @@ class TicketsDataProvider {
         Object.assign(node, refreshedNode);
         return node;
     }
-    async GetQueryResultsFromWiql(wiqlHref = '', displayAsTable = false, testCaseToRelatedWiMap) {
+    async GetQueryResultsFromWiql(wiqlHref = '', displayAsTable = false, testCaseToRelatedWiMap, fetchAllFields = false) {
         try {
             if (!wiqlHref) {
                 throw new Error('Incorrect WIQL Link');
@@ -816,13 +879,13 @@ class TicketsDataProvider {
                 case tfs_data_3.QueryType.OneHop:
                     return displayAsTable
                         ? await this.parseDirectLinkedQueryResultForTableFormat(queryResult, testCaseToRelatedWiMap)
-                        : await this.parseTreeQueryResult(queryResult);
+                        : await this.parseTreeQueryResult(queryResult, fetchAllFields);
                 case tfs_data_3.QueryType.Tree:
-                    return await this.parseTreeQueryResult(queryResult);
+                    return await this.parseTreeQueryResult(queryResult, fetchAllFields);
                 case tfs_data_3.QueryType.Flat:
                     return displayAsTable
                         ? await this.parseFlatQueryResultForTableFormat(queryResult)
-                        : await this.parseFlatQueryResult(queryResult);
+                        : await this.parseFlatQueryResult(queryResult, fetchAllFields);
                 default:
                     break;
             }
@@ -980,7 +1043,7 @@ class TicketsDataProvider {
             fieldsToIncludeMap,
         };
     }
-    async parseTreeQueryResult(queryResult) {
+    async parseTreeQueryResult(queryResult, fetchAllFields = false) {
         const { workItemRelations } = queryResult;
         if (!workItemRelations)
             return null;
@@ -993,10 +1056,10 @@ class TicketsDataProvider {
         for (const rel of workItemRelations) {
             const t = rel.target;
             if (!allItems[t.id])
-                await this.initTreeQueryResultItem(t, allItems);
+                await this.initTreeQueryResultItem(t, allItems, fetchAllFields);
             // Also initialize source nodes if they exist
             if (rel.source && !allItems[rel.source.id]) {
-                await this.initTreeQueryResultItem(rel.source, allItems);
+                await this.initTreeQueryResultItem(rel.source, allItems, fetchAllFields);
             }
             if (rel.rel === null && rel.source === null) {
                 if (!rootSet.has(t.id)) {
@@ -1022,11 +1085,11 @@ class TicketsDataProvider {
             // Nodes should already be initialized, but double-check
             if (!allItems[parentId]) {
                 logger_1.default.warn(`Parent ${parentId} not found, initializing now`);
-                await this.initTreeQueryResultItem(rel.source, allItems);
+                await this.initTreeQueryResultItem(rel.source, allItems, fetchAllFields);
             }
             if (!allItems[childId]) {
                 logger_1.default.warn(`Child ${childId} not found, initializing now`);
-                await this.initTreeQueryResultItem(rel.target, allItems);
+                await this.initTreeQueryResultItem(rel.target, allItems, fetchAllFields);
             }
             const parent = allItems[parentId];
             parent._childrenSet || (parent._childrenSet = new Set());
@@ -1053,32 +1116,38 @@ class TicketsDataProvider {
             allItems, // all fetched items (including those not in hierarchy)
         };
     }
-    async initTreeQueryResultItem(item, allItems) {
+    async initTreeQueryResultItem(item, allItems, fetchAllFields = false) {
         var _a, _b;
-        const urlWi = `${item.url}?fields=System.Description,System.Title,Microsoft.VSTS.TCM.ReproSteps,Microsoft.VSTS.CMMI.Symptom`;
+        const urlWi = fetchAllFields ? `${item.url}` : `${item.url}?fields=${WI_DEFAULT_FIELDS}`;
         const wi = await tfs_1.TFSServices.getItemContent(urlWi, this.token);
+        const fields = (wi === null || wi === void 0 ? void 0 : wi.fields) || {};
         // need to fetch the WI with only the the title, the web URL and the description
         allItems[item.id] = {
             id: item.id,
-            title: wi.fields['System.Title'] || '',
-            description: (_b = (_a = wi.fields['Microsoft.VSTS.CMMI.Symptom']) !== null && _a !== void 0 ? _a : wi.fields['System.Description']) !== null && _b !== void 0 ? _b : '',
+            title: fields['System.Title'] || '',
+            description: (_b = (_a = fields['Microsoft.VSTS.CMMI.Symptom']) !== null && _a !== void 0 ? _a : fields['System.Description']) !== null && _b !== void 0 ? _b : '',
             htmlUrl: wi._links.html.href,
+            fields,
+            workItemType: fields['System.WorkItemType'] || '',
             children: [],
         };
     }
-    async initFlatQueryResultItem(item, workItemMap) {
+    async initFlatQueryResultItem(item, workItemMap, fetchAllFields = false) {
         var _a, _b;
-        const urlWi = `${item.url}?fields=System.Description,System.Title,Microsoft.VSTS.TCM.ReproSteps,Microsoft.VSTS.CMMI.Symptom`;
+        const urlWi = fetchAllFields ? `${item.url}` : `${item.url}?fields=${WI_DEFAULT_FIELDS}`;
         const wi = await tfs_1.TFSServices.getItemContent(urlWi, this.token);
+        const fields = (wi === null || wi === void 0 ? void 0 : wi.fields) || {};
         // need to fetch the WI with only the the title, the web URL and the description
         workItemMap.set(item.id, {
             id: item.id,
-            title: wi.fields['System.Title'] || '',
-            description: (_b = (_a = wi.fields['Microsoft.VSTS.CMMI.Symptom']) !== null && _a !== void 0 ? _a : wi.fields['System.Description']) !== null && _b !== void 0 ? _b : '',
+            title: fields['System.Title'] || '',
+            description: (_b = (_a = fields['Microsoft.VSTS.CMMI.Symptom']) !== null && _a !== void 0 ? _a : fields['System.Description']) !== null && _b !== void 0 ? _b : '',
             htmlUrl: wi._links.html.href,
+            fields,
+            workItemType: fields['System.WorkItemType'] || '',
         });
     }
-    async parseFlatQueryResult(queryResult) {
+    async parseFlatQueryResult(queryResult, fetchAllFields = false) {
         const { workItems } = queryResult;
         if (!workItems) {
             logger_1.default.warn(`No work items were found for this requested query`);
@@ -1088,7 +1157,7 @@ class TicketsDataProvider {
             const workItemsResultMap = new Map();
             for (const wi of workItems) {
                 if (!workItemsResultMap.has(wi.id)) {
-                    await this.initFlatQueryResultItem(wi, workItemsResultMap);
+                    await this.initFlatQueryResultItem(wi, workItemsResultMap, fetchAllFields);
                 }
             }
             return [...workItemsResultMap.values()];
@@ -1153,6 +1222,485 @@ class TicketsDataProvider {
         var wiql = querie._links.wiql;
         return await this.GetQueryResultsByWiqlHref(wiql.href, project);
     }
+    normalizeHistoricalAsOf(value) {
+        const raw = String(value || '').trim();
+        if (!raw) {
+            throw new Error('asOf date-time is required');
+        }
+        const parsed = new Date(raw);
+        if (Number.isNaN(parsed.getTime())) {
+            throw new Error(`Invalid date-time value: ${raw}`);
+        }
+        return parsed.toISOString();
+    }
+    normalizeHistoricalCompareValue(value) {
+        if (value == null) {
+            return '';
+        }
+        if (typeof value === 'string') {
+            return value.replace(/\s+/g, ' ').trim();
+        }
+        if (Array.isArray(value)) {
+            return value
+                .map((item) => this.normalizeHistoricalCompareValue(item))
+                .filter((item) => item !== '')
+                .sort((a, b) => a.localeCompare(b))
+                .join('; ');
+        }
+        if (typeof value === 'object') {
+            const fallback = value;
+            if (typeof fallback.displayName === 'string') {
+                return this.normalizeHistoricalCompareValue(fallback.displayName);
+            }
+            if (typeof fallback.name === 'string') {
+                return this.normalizeHistoricalCompareValue(fallback.name);
+            }
+            return this.normalizeHistoricalCompareValue(JSON.stringify(value));
+        }
+        return String(value).trim();
+    }
+    normalizeTestPhaseValue(value) {
+        const rendered = this.normalizeHistoricalCompareValue(value);
+        if (!rendered) {
+            return '';
+        }
+        const parts = rendered
+            .split(/[;,]/)
+            .map((part) => part.trim())
+            .filter((part) => part.length > 0);
+        if (parts.length <= 1) {
+            return rendered;
+        }
+        const unique = Array.from(new Set(parts));
+        unique.sort((a, b) => a.localeCompare(b));
+        return unique.join('; ');
+    }
+    isTestCaseType(workItemType) {
+        const normalized = String(workItemType || '').trim().toLowerCase();
+        return normalized === 'test case' || normalized === 'testcase';
+    }
+    toHistoricalRevision(value) {
+        const n = Number(value);
+        if (!Number.isFinite(n)) {
+            return null;
+        }
+        return n;
+    }
+    extractHistoricalWorkItemIds(queryResult) {
+        var _a, _b;
+        const ids = new Set();
+        const pushId = (candidate) => {
+            const n = Number(candidate);
+            if (Number.isFinite(n)) {
+                ids.add(n);
+            }
+        };
+        const workItems = Array.isArray(queryResult === null || queryResult === void 0 ? void 0 : queryResult.workItems) ? queryResult.workItems : [];
+        for (const workItem of workItems) {
+            pushId(workItem === null || workItem === void 0 ? void 0 : workItem.id);
+        }
+        const workItemRelations = Array.isArray(queryResult === null || queryResult === void 0 ? void 0 : queryResult.workItemRelations)
+            ? queryResult.workItemRelations
+            : [];
+        for (const relation of workItemRelations) {
+            pushId((_a = relation === null || relation === void 0 ? void 0 : relation.source) === null || _a === void 0 ? void 0 : _a.id);
+            pushId((_b = relation === null || relation === void 0 ? void 0 : relation.target) === null || _b === void 0 ? void 0 : _b.id);
+        }
+        return Array.from(ids.values()).sort((a, b) => a - b);
+    }
+    appendAsOfToWiql(wiql, asOfIso) {
+        const raw = String(wiql || '').trim();
+        if (!raw) {
+            return '';
+        }
+        const withoutAsOf = raw.replace(/\s+ASOF\s+'[^']*'/i, '');
+        return `${withoutAsOf} ASOF '${asOfIso}'`;
+    }
+    appendApiVersion(url, apiVersion) {
+        if (!apiVersion) {
+            return url;
+        }
+        const separator = url.includes('?') ? '&' : '?';
+        return `${url}${separator}api-version=${encodeURIComponent(apiVersion)}`;
+    }
+    shouldRetryHistoricalWithLowerVersion(error) {
+        var _a, _b, _c;
+        const status = Number(((_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.status) || 0);
+        if (status === 401 || status === 403) {
+            return false;
+        }
+        if (status >= 500) {
+            return true;
+        }
+        if ([400, 404, 405, 406, 410].includes(status)) {
+            return true;
+        }
+        const message = String(((_c = (_b = error === null || error === void 0 ? void 0 : error.response) === null || _b === void 0 ? void 0 : _b.data) === null || _c === void 0 ? void 0 : _c.message) || (error === null || error === void 0 ? void 0 : error.message) || '');
+        return /api[- ]?version/i.test(message);
+    }
+    async withHistoricalApiVersionFallback(operation, task) {
+        var _a;
+        let lastError = null;
+        for (const apiVersion of HISTORICAL_WIT_API_VERSIONS) {
+            try {
+                const result = await task(apiVersion);
+                return { apiVersion, result };
+            }
+            catch (error) {
+                lastError = error;
+                const status = Number(((_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.status) || 0);
+                const apiVersionLabel = apiVersion || 'default';
+                logger_1.default.warn(`[${operation}] failed with api-version=${apiVersionLabel}${status ? ` (status ${status})` : ''}`);
+                if (!this.shouldRetryHistoricalWithLowerVersion(error) ||
+                    apiVersion === HISTORICAL_WIT_API_VERSIONS[HISTORICAL_WIT_API_VERSIONS.length - 1]) {
+                    throw error;
+                }
+            }
+        }
+        throw lastError || new Error(`[${operation}] Failed to execute historical request`);
+    }
+    chunkHistoricalWorkItemIds(ids) {
+        const chunks = [];
+        for (let i = 0; i < ids.length; i += HISTORICAL_BATCH_MAX_IDS) {
+            chunks.push(ids.slice(i, i + HISTORICAL_BATCH_MAX_IDS));
+        }
+        return chunks;
+    }
+    normalizeHistoricalQueryPath(path) {
+        const rawPath = String(path || '').trim();
+        const normalizedRoot = rawPath.toLowerCase();
+        if (rawPath === '' ||
+            normalizedRoot === 'shared' ||
+            normalizedRoot === 'shared queries') {
+            return 'Shared%20Queries';
+        }
+        const segments = rawPath
+            .replace(/\\/g, '/')
+            .split('/')
+            .filter((segment) => segment.trim() !== '')
+            .map((segment) => {
+            try {
+                return encodeURIComponent(decodeURIComponent(segment));
+            }
+            catch (error) {
+                return encodeURIComponent(segment);
+            }
+        });
+        return segments.join('/');
+    }
+    normalizeHistoricalQueryRoot(root) {
+        if (!root)
+            return root;
+        if (Array.isArray(root === null || root === void 0 ? void 0 : root.children) || typeof (root === null || root === void 0 ? void 0 : root.isFolder) === 'boolean') {
+            return root;
+        }
+        if (Array.isArray(root === null || root === void 0 ? void 0 : root.value)) {
+            return {
+                id: 'root',
+                name: 'Shared Queries',
+                isFolder: true,
+                children: root.value,
+            };
+        }
+        return root;
+    }
+    async fetchHistoricalWorkItemsBatch(project, ids, asOf, apiVersion) {
+        const workItemsBatchUrl = this.appendApiVersion(`${this.orgUrl}${project}/_apis/wit/workitemsbatch`, apiVersion);
+        const idChunks = this.chunkHistoricalWorkItemIds(ids);
+        try {
+            const batchResponses = await Promise.all(idChunks.map((idChunk) => this.limit(() => tfs_1.TFSServices.getItemContent(workItemsBatchUrl, this.token, 'post', {
+                ids: idChunk,
+                asOf,
+                $expand: 'Relations',
+                fields: HISTORICAL_WORK_ITEM_FIELDS,
+            }))));
+            return batchResponses.flatMap((batch) => (Array.isArray(batch === null || batch === void 0 ? void 0 : batch.value) ? batch.value : []));
+        }
+        catch (error) {
+            logger_1.default.warn(`[historical-workitems] workitemsbatch failed${apiVersion ? ` (api-version=${apiVersion})` : ''}, falling back to per-item retrieval: ${(error === null || error === void 0 ? void 0 : error.message) || error}`);
+            const asOfParam = encodeURIComponent(asOf);
+            const responses = await Promise.all(ids.map((id) => this.limit(() => {
+                const itemUrl = this.appendApiVersion(`${this.orgUrl}${project}/_apis/wit/workitems/${id}?$expand=Relations&asOf=${asOfParam}`, apiVersion);
+                return tfs_1.TFSServices.getItemContent(itemUrl, this.token);
+            })));
+            return responses.filter((item) => item && typeof item === 'object');
+        }
+    }
+    async executeHistoricalQueryAtAsOf(project, queryId, asOfIso) {
+        const { apiVersion, result } = await this.withHistoricalApiVersionFallback('historical-query-execution', async (resolvedApiVersion) => {
+            const queryDefUrl = this.appendApiVersion(`${this.orgUrl}${project}/_apis/wit/queries/${encodeURIComponent(queryId)}?$expand=all`, resolvedApiVersion);
+            const queryDefinition = await tfs_1.TFSServices.getItemContent(queryDefUrl, this.token);
+            const wiqlText = String((queryDefinition === null || queryDefinition === void 0 ? void 0 : queryDefinition.wiql) || '').trim();
+            let queryResult = null;
+            try {
+                if (!wiqlText) {
+                    throw new Error(`Could not resolve WIQL text for query ${queryId}`);
+                }
+                const wiqlWithAsOf = this.appendAsOfToWiql(wiqlText, asOfIso);
+                if (!wiqlWithAsOf) {
+                    throw new Error(`Could not build WIQL for historical query ${queryId}`);
+                }
+                const executeUrl = this.appendApiVersion(`${this.orgUrl}${project}/_apis/wit/wiql?$top=2147483646&timePrecision=true`, resolvedApiVersion);
+                queryResult = await tfs_1.TFSServices.getItemContent(executeUrl, this.token, 'post', {
+                    query: wiqlWithAsOf,
+                });
+            }
+            catch (inlineWiqlError) {
+                logger_1.default.warn(`[historical-query-execution] inline WIQL failed for query ${queryId}${resolvedApiVersion ? ` (api-version=${resolvedApiVersion})` : ''}, trying WIQL-by-id fallback: ${(inlineWiqlError === null || inlineWiqlError === void 0 ? void 0 : inlineWiqlError.message) || inlineWiqlError}`);
+                const executeByIdUrl = this.appendApiVersion(`${this.orgUrl}${project}/_apis/wit/wiql/${encodeURIComponent(queryId)}?$top=2147483646&timePrecision=true&asOf=${encodeURIComponent(asOfIso)}`, resolvedApiVersion);
+                queryResult = await tfs_1.TFSServices.getItemContent(executeByIdUrl, this.token);
+            }
+            return { queryDefinition, queryResult };
+        });
+        return Object.assign(Object.assign({}, result), { apiVersion });
+    }
+    toHistoricalWorkItemSnapshot(project, workItem) {
+        var _a, _b, _c, _d;
+        const fields = ((workItem === null || workItem === void 0 ? void 0 : workItem.fields) || {});
+        const id = Number((workItem === null || workItem === void 0 ? void 0 : workItem.id) || fields['System.Id'] || 0);
+        const workItemType = this.normalizeHistoricalCompareValue(fields['System.WorkItemType']);
+        const testPhaseRaw = (_c = (_b = (_a = fields['Elisra.TestPhase']) !== null && _a !== void 0 ? _a : fields['Custom.TestPhase']) !== null && _b !== void 0 ? _b : fields['Elisra.Testphase']) !== null && _c !== void 0 ? _c : fields['Custom.Testphase'];
+        const relatedLinkCount = Array.isArray(workItem === null || workItem === void 0 ? void 0 : workItem.relations) ? workItem.relations.length : 0;
+        return {
+            id,
+            workItemType,
+            title: this.normalizeHistoricalCompareValue(fields['System.Title']),
+            state: this.normalizeHistoricalCompareValue(fields['System.State']),
+            areaPath: this.normalizeHistoricalCompareValue(fields['System.AreaPath']),
+            iterationPath: this.normalizeHistoricalCompareValue(fields['System.IterationPath']),
+            versionId: this.toHistoricalRevision((_d = workItem === null || workItem === void 0 ? void 0 : workItem.rev) !== null && _d !== void 0 ? _d : fields['System.Rev']),
+            versionTimestamp: this.normalizeHistoricalCompareValue(fields['System.ChangedDate']),
+            description: this.normalizeHistoricalCompareValue(fields['System.Description']),
+            steps: this.normalizeHistoricalCompareValue(fields['Microsoft.VSTS.TCM.Steps']),
+            testPhase: this.normalizeTestPhaseValue(testPhaseRaw),
+            relatedLinkCount,
+            workItemUrl: `${this.orgUrl}${project}/_workitems/edit/${id}`,
+        };
+    }
+    async getHistoricalSnapshot(project, queryId, asOfInput) {
+        const asOf = this.normalizeHistoricalAsOf(asOfInput);
+        const { queryDefinition, queryResult, apiVersion } = await this.executeHistoricalQueryAtAsOf(project, queryId, asOf);
+        const ids = this.extractHistoricalWorkItemIds(queryResult);
+        if (ids.length === 0) {
+            return {
+                queryId,
+                queryName: String((queryDefinition === null || queryDefinition === void 0 ? void 0 : queryDefinition.name) || queryId),
+                asOf,
+                total: 0,
+                rows: [],
+                snapshotMap: new Map(),
+            };
+        }
+        const values = await this.fetchHistoricalWorkItemsBatch(project, ids, asOf, apiVersion);
+        const rows = values
+            .map((workItem) => this.toHistoricalWorkItemSnapshot(project, workItem))
+            .sort((a, b) => a.id - b.id);
+        const snapshotMap = new Map();
+        for (const row of rows) {
+            snapshotMap.set(row.id, row);
+        }
+        return {
+            queryId,
+            queryName: String((queryDefinition === null || queryDefinition === void 0 ? void 0 : queryDefinition.name) || queryId),
+            asOf,
+            total: rows.length,
+            rows,
+            snapshotMap,
+        };
+    }
+    collectHistoricalQueries(root, parentPath = '') {
+        const items = [];
+        if (!root) {
+            return items;
+        }
+        const name = String((root === null || root === void 0 ? void 0 : root.name) || '').trim();
+        const currentPath = parentPath && name ? `${parentPath}/${name}` : name || parentPath;
+        if (!(root === null || root === void 0 ? void 0 : root.isFolder)) {
+            const id = String((root === null || root === void 0 ? void 0 : root.id) || '').trim();
+            if (id) {
+                items.push({
+                    id,
+                    queryName: name || id,
+                    path: parentPath || 'Shared Queries',
+                });
+            }
+            return items;
+        }
+        const children = Array.isArray(root === null || root === void 0 ? void 0 : root.children) ? root.children : [];
+        for (const child of children) {
+            items.push(...this.collectHistoricalQueries(child, currentPath || 'Shared Queries'));
+        }
+        return items;
+    }
+    /**
+     * Returns a flat list of shared queries for historical/as-of execution.
+     */
+    async GetHistoricalQueries(project, path = 'shared') {
+        const normalizedPath = this.normalizeHistoricalQueryPath(path);
+        // Azure DevOps WIT query tree endpoint enforces $depth range 0..2.
+        const depth = 2;
+        const { result: root } = await this.withHistoricalApiVersionFallback('historical-queries-list', (apiVersion) => {
+            const url = this.appendApiVersion(`${this.orgUrl}${project}/_apis/wit/queries/${normalizedPath}?$depth=${depth}&$expand=all`, apiVersion);
+            return tfs_1.TFSServices.getItemContent(url, this.token);
+        });
+        const normalizedRoot = this.normalizeHistoricalQueryRoot(root);
+        const items = this.collectHistoricalQueries(normalizedRoot).filter((query) => query.id !== '');
+        items.sort((a, b) => {
+            const byPath = a.path.localeCompare(b.path);
+            if (byPath !== 0)
+                return byPath;
+            return a.queryName.localeCompare(b.queryName);
+        });
+        return items;
+    }
+    /**
+     * Runs a shared query as-of a specific date-time and returns a flat work-item table snapshot.
+     */
+    async GetHistoricalQueryResults(queryId, project, asOfInput) {
+        const snapshot = await this.getHistoricalSnapshot(project, queryId, asOfInput);
+        return {
+            queryId: snapshot.queryId,
+            queryName: snapshot.queryName,
+            asOf: snapshot.asOf,
+            total: snapshot.total,
+            rows: snapshot.rows.map((row) => ({
+                id: row.id,
+                workItemType: row.workItemType,
+                title: row.title,
+                state: row.state,
+                areaPath: row.areaPath,
+                iterationPath: row.iterationPath,
+                versionId: row.versionId,
+                versionTimestamp: row.versionTimestamp,
+                workItemUrl: row.workItemUrl,
+            })),
+        };
+    }
+    /**
+     * Compares a shared query between two date-time baselines using the feature's noise-control fields.
+     */
+    async CompareHistoricalQueryResults(queryId, project, baselineAsOfInput, compareToAsOfInput) {
+        const [baseline, compareTo] = await Promise.all([
+            this.getHistoricalSnapshot(project, queryId, baselineAsOfInput),
+            this.getHistoricalSnapshot(project, queryId, compareToAsOfInput),
+        ]);
+        const allIds = new Set([
+            ...Array.from(baseline.snapshotMap.keys()),
+            ...Array.from(compareTo.snapshotMap.keys()),
+        ]);
+        const sortedIds = Array.from(allIds.values()).sort((a, b) => a - b);
+        const rows = sortedIds.map((id) => {
+            const baselineRow = baseline.snapshotMap.get(id) || null;
+            const compareToRow = compareTo.snapshotMap.get(id) || null;
+            const workItemType = (compareToRow === null || compareToRow === void 0 ? void 0 : compareToRow.workItemType) || (baselineRow === null || baselineRow === void 0 ? void 0 : baselineRow.workItemType) || '';
+            const isTestCase = this.isTestCaseType(workItemType);
+            if (baselineRow && !compareToRow) {
+                return {
+                    id,
+                    workItemType,
+                    title: baselineRow.title,
+                    baselineRevisionId: baselineRow.versionId,
+                    compareToRevisionId: null,
+                    compareStatus: 'Deleted',
+                    changedFields: [],
+                    differences: [],
+                    workItemUrl: baselineRow.workItemUrl,
+                };
+            }
+            if (!baselineRow && compareToRow) {
+                return {
+                    id,
+                    workItemType,
+                    title: compareToRow.title,
+                    baselineRevisionId: null,
+                    compareToRevisionId: compareToRow.versionId,
+                    compareStatus: 'Added',
+                    changedFields: [],
+                    differences: [],
+                    workItemUrl: compareToRow.workItemUrl,
+                };
+            }
+            const safeBaseline = baselineRow;
+            const safeCompareTo = compareToRow;
+            const changedFields = [];
+            if (safeBaseline.description !== safeCompareTo.description) {
+                changedFields.push('Description');
+            }
+            if (safeBaseline.title !== safeCompareTo.title) {
+                changedFields.push('Title');
+            }
+            if (safeBaseline.state !== safeCompareTo.state) {
+                changedFields.push('State');
+            }
+            if (isTestCase && safeBaseline.steps !== safeCompareTo.steps) {
+                changedFields.push('Steps');
+            }
+            if (safeBaseline.testPhase !== safeCompareTo.testPhase) {
+                changedFields.push('Test Phase');
+            }
+            if (isTestCase && safeBaseline.relatedLinkCount !== safeCompareTo.relatedLinkCount) {
+                changedFields.push('Related Link Count');
+            }
+            const differences = changedFields.map((field) => {
+                switch (field) {
+                    case 'Description':
+                        return { field, baseline: safeBaseline.description, compareTo: safeCompareTo.description };
+                    case 'Title':
+                        return { field, baseline: safeBaseline.title, compareTo: safeCompareTo.title };
+                    case 'State':
+                        return { field, baseline: safeBaseline.state, compareTo: safeCompareTo.state };
+                    case 'Steps':
+                        return { field, baseline: safeBaseline.steps, compareTo: safeCompareTo.steps };
+                    case 'Test Phase':
+                        return { field, baseline: safeBaseline.testPhase, compareTo: safeCompareTo.testPhase };
+                    case 'Related Link Count':
+                        return {
+                            field,
+                            baseline: String(safeBaseline.relatedLinkCount),
+                            compareTo: String(safeCompareTo.relatedLinkCount),
+                        };
+                    default:
+                        return { field, baseline: '', compareTo: '' };
+                }
+            });
+            return {
+                id,
+                workItemType,
+                title: safeCompareTo.title || safeBaseline.title,
+                baselineRevisionId: safeBaseline.versionId,
+                compareToRevisionId: safeCompareTo.versionId,
+                compareStatus: changedFields.length > 0 ? 'Changed' : 'No changes',
+                changedFields,
+                differences,
+                workItemUrl: safeCompareTo.workItemUrl || safeBaseline.workItemUrl,
+            };
+        });
+        const summary = rows.reduce((acc, row) => {
+            if (row.compareStatus === 'Added')
+                acc.addedCount += 1;
+            else if (row.compareStatus === 'Deleted')
+                acc.deletedCount += 1;
+            else if (row.compareStatus === 'Changed')
+                acc.changedCount += 1;
+            else
+                acc.noChangeCount += 1;
+            return acc;
+        }, { addedCount: 0, deletedCount: 0, changedCount: 0, noChangeCount: 0 });
+        return {
+            queryId,
+            queryName: compareTo.queryName || baseline.queryName || queryId,
+            baseline: {
+                asOf: baseline.asOf,
+                total: baseline.total,
+            },
+            compareTo: {
+                asOf: compareTo.asOf,
+                total: compareTo.total,
+            },
+            summary: Object.assign(Object.assign({}, summary), { updatedCount: summary.changedCount }),
+            rows,
+        };
+    }
     async PopulateWorkItemsByIds(workItemsArray = [], projectName = '') {
         let url = `${this.orgUrl}${projectName}/_apis/wit/workitemsbatch`;
         let res = [];