@elisra-devops/docgen-data-provider 1.138.0 → 1.140.0

package/bin/modules/TicketsDataProvider.d.ts

@@ -10,7 +10,7 @@ export default class TicketsDataProvider {
     token: string;
     queriesList: Array<any>;
     private limit;
-    private historicalFieldsOverride;
+    private historicalTestPhaseFieldByProject;
     constructor(orgUrl: string, token: string);
     /**
      * Extracts the Azure DevOps project name from a WIQL URL.
@@ -202,6 +202,25 @@ export default class TicketsDataProvider {
     }>;
     private normalizeHistoricalAsOf;
     private normalizeHistoricalCompareValue;
+    /**
+     * Stores rich-text fields (Description, Steps) with only whitespace trimmed, preserving markup
+     * so the report renderer can clean/render it faithfully. Equality between two snapshots must go
+     * through canonicalizeHistoricalRichTextForCompare instead of comparing this value directly.
+     */
+    private rawHistoricalRichText;
+    /**
+     * Canonicalizes a rich-text field for equality comparison only. Intentionally identical to the
+     * whitespace collapse previously applied at storage time, so Changed/No-changes verdicts and
+     * summary counts are unaffected by storing the raw value for rendering.
+     */
+    private canonicalizeHistoricalRichTextForCompare;
+    /**
+     * Parses baseline/compareTo Steps XML into per-step Action/Expected arrays for a changed test
+     * case, so the report can render readable steps instead of raw Steps XML. Best-effort: a parse
+     * failure (malformed XML, shared-step lookup error) must not fail the whole comparison, so it
+     * logs and falls back to leaving the caller with only the raw XML strings.
+     */
+    private parseHistoricalStepsForDiff;
     private normalizeTestPhaseValue;
     private isTestCaseType;
     private toHistoricalRevision;
@@ -216,8 +235,8 @@ export default class TicketsDataProvider {
     private historicalErrorMessage;
     private isHistoricalMissingWorkItemError;
     private isHistoricalUnknownFieldError;
-    private extractHistoricalUnknownFieldName;
-    private fetchHistoricalFieldsBatchAttempt;
+    private resolveHistoricalTestPhaseField;
+    private discoverHistoricalTestPhaseField;
     private fetchHistoricalFieldsBatch;
     private fetchHistoricalWorkItemsBatch;
     private executeHistoricalQueryAtAsOf;

package/bin/modules/TicketsDataProvider.js

@@ -8,6 +8,7 @@ const tfs_data_3 = require("../models/tfs-data");
 const tfs_data_4 = require("../models/tfs-data");
 const tfs_data_5 = require("../models/tfs-data");
 const tfs_data_6 = require("../models/tfs-data");
+const testStepParserHelper_1 = require("../utils/testStepParserHelper");
 const logger_1 = require("../utils/logger");
 const pLimit = require('p-limit');
 const HISTORICAL_WIT_API_VERSIONS = ['7.1', '5.1', null];
@@ -45,9 +46,11 @@ class TicketsDataProvider {
         this.token = '';
         this.queriesList = new Array();
         this.limit = pLimit(10);
-        // Set once a workitemsbatch call reports one of HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS
-        // as unknown for this project, so only the first chunk pays the retry cost.
-        this.historicalFieldsOverride = null;
+        // Resolved once per project via resolveHistoricalTestPhaseField, so a
+        // compare's baseline and compareTo snapshots (and repeated queries against
+        // the same provider instance) only pay the discovery call once. Value is
+        // the real reference name, or null if the project defines no such field.
+        this.historicalTestPhaseFieldByProject = new Map();
         this.orgUrl = orgUrl;
         this.token = token;
     }
@@ -1409,6 +1412,52 @@ class TicketsDataProvider {
         }
         return String(value).trim();
     }
+    /**
+     * Stores rich-text fields (Description, Steps) with only whitespace trimmed, preserving markup
+     * so the report renderer can clean/render it faithfully. Equality between two snapshots must go
+     * through canonicalizeHistoricalRichTextForCompare instead of comparing this value directly.
+     */
+    rawHistoricalRichText(value) {
+        if (value == null) {
+            return '';
+        }
+        if (typeof value === 'string') {
+            return value.trim();
+        }
+        return this.normalizeHistoricalCompareValue(value);
+    }
+    /**
+     * Canonicalizes a rich-text field for equality comparison only. Intentionally identical to the
+     * whitespace collapse previously applied at storage time, so Changed/No-changes verdicts and
+     * summary counts are unaffected by storing the raw value for rendering.
+     */
+    canonicalizeHistoricalRichTextForCompare(value) {
+        return this.normalizeHistoricalCompareValue(value);
+    }
+    /**
+     * Parses baseline/compareTo Steps XML into per-step Action/Expected arrays for a changed test
+     * case, so the report can render readable steps instead of raw Steps XML. Best-effort: a parse
+     * failure (malformed XML, shared-step lookup error) must not fail the whole comparison, so it
+     * logs and falls back to leaving the caller with only the raw XML strings.
+     */
+    async parseHistoricalStepsForDiff(testStepParserHelper, baselineStepsXml, compareToStepsXml) {
+        try {
+            const emptyRevisionMap = new Map();
+            const [baselineSteps, compareToSteps] = await Promise.all([
+                baselineStepsXml
+                    ? testStepParserHelper.parseTestSteps(baselineStepsXml, emptyRevisionMap)
+                    : Promise.resolve([]),
+                compareToStepsXml
+                    ? testStepParserHelper.parseTestSteps(compareToStepsXml, emptyRevisionMap)
+                    : Promise.resolve([]),
+            ]);
+            return { baselineSteps, compareToSteps };
+        }
+        catch (err) {
+            logger_1.default.warn(`Failed to parse historical Steps XML for diff rendering: ${(err === null || err === void 0 ? void 0 : err.message) || err}`);
+            return null;
+        }
+    }
     normalizeTestPhaseValue(value) {
         const rendered = this.normalizeHistoricalCompareValue(value);
         if (!rendered) {
@@ -1589,59 +1638,80 @@ class TicketsDataProvider {
         const message = this.historicalErrorMessage(error);
         return /TF51535|Cannot find field/i.test(message);
     }
-    // ADO's TF51535 names the specific field it couldn't find, e.g.
-    // "TF51535: Cannot find field 'Elisra.TestPhase'." — different networks
-    // define this optional field under different reference names (Elisra.* vs
-    // Custom.*), so drop only the one ADO actually rejected rather than every
-    // optional field, or a network that defines Custom.TestPhase but not
-    // Elisra.TestPhase would lose Test Phase comparison entirely for no reason.
-    extractHistoricalUnknownFieldName(error) {
-        const message = this.historicalErrorMessage(error);
-        const quoted = message.match(/Cannot find field\s*'([^']+)'/i);
-        if (quoted === null || quoted === void 0 ? void 0 : quoted[1])
-            return quoted[1];
-        return HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS.find((field) => message.includes(field)) || null;
+    // Different networks define the "Test Phase" custom field under different
+    // reference names (Elisra.TestPhase vs Custom.TestPhase, or something else
+    // entirely on a third network) — hardcoding candidate names and guessing is
+    // inherently fragile. Resolve the project's real field list once (Fields -
+    // List: GET {org}/{project}/_apis/wit/fields, supported since old TFS API
+    // versions) and use whichever reference name actually matches, by
+    // reference name or by friendly name. Resolves to null if the project
+    // defines no such field at all.
+    //
+    // Caches the in-flight promise, not just the resolved value: a compare's
+    // baseline and compareTo snapshots run concurrently against the same
+    // provider instance, and both would otherwise read the cache before either
+    // had a value to store, issuing the discovery request twice.
+    resolveHistoricalTestPhaseField(project, apiVersion) {
+        const cached = this.historicalTestPhaseFieldByProject.get(project);
+        if (cached)
+            return cached;
+        const promise = this.discoverHistoricalTestPhaseField(project, apiVersion);
+        this.historicalTestPhaseFieldByProject.set(project, promise);
+        return promise;
+    }
+    async discoverHistoricalTestPhaseField(project, apiVersion) {
+        const fieldsUrl = this.appendApiVersion(`${this.orgUrl}${project}/_apis/wit/fields`, apiVersion);
+        try {
+            const response = await tfs_1.TFSServices.getItemContent(fieldsUrl, this.token);
+            const fields = Array.isArray(response === null || response === void 0 ? void 0 : response.value) ? response.value : [];
+            const match = fields.find((field) => HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS.some((candidate) => String((field === null || field === void 0 ? void 0 : field.referenceName) || '').toLowerCase() === candidate.toLowerCase())) || fields.find((field) => /test\s*phase/i.test(String((field === null || field === void 0 ? void 0 : field.name) || '')));
+            const resolved = (match === null || match === void 0 ? void 0 : match.referenceName) ? String(match.referenceName) : null;
+            if (!resolved) {
+                logger_1.default.warn(`[historical-workitems] no Test Phase field defined for project '${project}'`);
+            }
+            return resolved;
+        }
+        catch (error) {
+            logger_1.default.warn(`[historical-workitems] could not list fields for project '${project}' to resolve the ` +
+                `Test Phase field name, omitting it: ${this.historicalErrorMessage(error)}`);
+            return null;
+        }
     }
-    fetchHistoricalFieldsBatchAttempt(workItemsBatchUrl, idChunk, asOf, fieldsForRequest, attemptsRemaining) {
+    fetchHistoricalFieldsBatch(workItemsBatchUrl, idChunk, asOf, project, fieldsForRequest) {
         return this.limit(() => tfs_1.TFSServices.getItemContent(workItemsBatchUrl, this.token, 'post', {
             ids: idChunk,
             asOf,
             fields: fieldsForRequest,
             errorPolicy: 'Omit',
         })).catch((error) => {
-            if (attemptsRemaining <= 0 || !this.isHistoricalUnknownFieldError(error)) {
-                throw error;
-            }
-            const unknownField = this.extractHistoricalUnknownFieldName(error);
-            // Only strip fields this call actually recognizes as droppable
-            // (named explicitly, or one of the known optional fields as a
-            // last-resort fallback if the message doesn't parse) — never strip a
-            // required field, so an unrelated schema issue still surfaces as an
-            // error instead of silently losing data.
-            const reducedFields = unknownField
-                ? fieldsForRequest.filter((field) => field !== unknownField)
-                : fieldsForRequest.filter((field) => !HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS.includes(field));
-            if (reducedFields.length === fieldsForRequest.length) {
+            // Defensive net: the resolved field name came from the project's own
+            // field list, so this shouldn't fire, but if it somehow still does,
+            // fall back to the required fields and poison the cache so later
+            // chunks/queries for this project stop requesting it too.
+            const hasOptionalField = HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS.some((f) => fieldsForRequest.includes(f))
+                || fieldsForRequest.some((f) => !HISTORICAL_REQUIRED_WORK_ITEM_FIELDS.includes(f));
+            if (!hasOptionalField || !this.isHistoricalUnknownFieldError(error)) {
                 throw error;
             }
-            // Concurrent chunks can each discover a different bad field before any
-            // of them updates the shared override — intersect rather than
-            // overwrite, so one chunk's retry never re-requests a field another
-            // chunk already proved invalid for this project.
-            this.historicalFieldsOverride = this.historicalFieldsOverride
-                ? this.historicalFieldsOverride.filter((field) => reducedFields.includes(field))
-                : reducedFields;
-            logger_1.default.warn(`[historical-workitems] field${unknownField ? ` '${unknownField}'` : '(s)'} not defined ` +
-                `for this project; retrying workitemsbatch without it: ${this.historicalErrorMessage(error)}`);
-            return this.fetchHistoricalFieldsBatchAttempt(workItemsBatchUrl, idChunk, asOf, reducedFields, attemptsRemaining - 1);
+            logger_1.default.warn(`[historical-workitems] resolved Test Phase field was rejected by workitemsbatch for ` +
+                `project '${project}'; retrying without it: ${this.historicalErrorMessage(error)}`);
+            this.historicalTestPhaseFieldByProject.set(project, Promise.resolve(null));
+            return this.limit(() => tfs_1.TFSServices.getItemContent(workItemsBatchUrl, this.token, 'post', {
+                ids: idChunk,
+                asOf,
+                fields: HISTORICAL_REQUIRED_WORK_ITEM_FIELDS,
+                errorPolicy: 'Omit',
+            }));
         });
     }
-    fetchHistoricalFieldsBatch(workItemsBatchUrl, idChunk, asOf) {
-        const fieldsForRequest = this.historicalFieldsOverride || HISTORICAL_WORK_ITEM_FIELDS;
-        return this.fetchHistoricalFieldsBatchAttempt(workItemsBatchUrl, idChunk, asOf, fieldsForRequest, HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS.length);
-    }
     async fetchHistoricalWorkItemsBatch(project, ids, asOf, apiVersion) {
         const workItemsBatchUrl = this.appendApiVersion(`${this.orgUrl}${project}/_apis/wit/workitemsbatch`, apiVersion);
+        // Resolved once per project, before any chunk starts, so every chunk
+        // shares the same field list — no per-request guessing or retry race.
+        const testPhaseField = await this.resolveHistoricalTestPhaseField(project, apiVersion);
+        const fieldsForRequest = testPhaseField
+            ? [...HISTORICAL_REQUIRED_WORK_ITEM_FIELDS, testPhaseField]
+            : HISTORICAL_REQUIRED_WORK_ITEM_FIELDS;
         const idChunks = this.chunkHistoricalWorkItemIds(ids);
         try {
             const chunkResults = await Promise.all(idChunks.map((idChunk) => 
@@ -1657,7 +1727,7 @@ class TicketsDataProvider {
             // two units against the shared concurrency cap, not one — otherwise
             // the real ceiling on simultaneous ADO calls would silently double.
             Promise.all([
-                this.fetchHistoricalFieldsBatch(workItemsBatchUrl, idChunk, asOf),
+                this.fetchHistoricalFieldsBatch(workItemsBatchUrl, idChunk, asOf, project, fieldsForRequest),
                 this.limit(() => tfs_1.TFSServices.getItemContent(workItemsBatchUrl, this.token, 'post', {
                     ids: idChunk,
                     asOf,
@@ -1780,8 +1850,8 @@ class TicketsDataProvider {
             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']),
+            description: this.rawHistoricalRichText(fields['System.Description']),
+            steps: this.rawHistoricalRichText(fields['Microsoft.VSTS.TCM.Steps']),
             testPhase: this.normalizeTestPhaseValue(testPhaseRaw),
             relatedLinkCount,
             workItemUrl: `${this.orgUrl}${project}/_workitems/edit/${id}`,
@@ -1917,7 +1987,8 @@ class TicketsDataProvider {
             ...Array.from(compareTo.snapshotMap.keys()),
         ]);
         const sortedIds = Array.from(allIds.values()).sort((a, b) => a - b);
-        const rows = sortedIds.map((id) => {
+        const testStepParserHelper = new testStepParserHelper_1.default(this.orgUrl, this.token);
+        const rows = await Promise.all(sortedIds.map(async (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) || '';
@@ -1951,7 +2022,12 @@ class TicketsDataProvider {
             const safeBaseline = baselineRow;
             const safeCompareTo = compareToRow;
             const changedFields = [];
-            if (safeBaseline.description !== safeCompareTo.description) {
+            const descriptionChanged = this.canonicalizeHistoricalRichTextForCompare(safeBaseline.description) !==
+                this.canonicalizeHistoricalRichTextForCompare(safeCompareTo.description);
+            const stepsChanged = isTestCase &&
+                this.canonicalizeHistoricalRichTextForCompare(safeBaseline.steps) !==
+                    this.canonicalizeHistoricalRichTextForCompare(safeCompareTo.steps);
+            if (descriptionChanged) {
                 changedFields.push('Description');
             }
             if (safeBaseline.title !== safeCompareTo.title) {
@@ -1960,7 +2036,7 @@ class TicketsDataProvider {
             if (safeBaseline.state !== safeCompareTo.state) {
                 changedFields.push('State');
             }
-            if (isTestCase && safeBaseline.steps !== safeCompareTo.steps) {
+            if (stepsChanged) {
                 changedFields.push('Steps');
             }
             if (safeBaseline.testPhase !== safeCompareTo.testPhase) {
@@ -1969,7 +2045,7 @@ class TicketsDataProvider {
             if (isTestCase && safeBaseline.relatedLinkCount !== safeCompareTo.relatedLinkCount) {
                 changedFields.push('Related Link Count');
             }
-            const differences = changedFields.map((field) => {
+            const differences = await Promise.all(changedFields.map(async (field) => {
                 switch (field) {
                     case 'Description':
                         return { field, baseline: safeBaseline.description, compareTo: safeCompareTo.description };
@@ -1977,8 +2053,10 @@ class TicketsDataProvider {
                         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 'Steps': {
+                        const parsed = await this.parseHistoricalStepsForDiff(testStepParserHelper, safeBaseline.steps, safeCompareTo.steps);
+                        return Object.assign({ field, baseline: safeBaseline.steps, compareTo: safeCompareTo.steps }, (parsed || {}));
+                    }
                     case 'Test Phase':
                         return { field, baseline: safeBaseline.testPhase, compareTo: safeCompareTo.testPhase };
                     case 'Related Link Count':
@@ -1990,7 +2068,7 @@ class TicketsDataProvider {
                     default:
                         return { field, baseline: '', compareTo: '' };
                 }
-            });
+            }));
             return {
                 id,
                 workItemType,
@@ -2002,7 +2080,7 @@ class TicketsDataProvider {
                 differences,
                 workItemUrl: safeCompareTo.workItemUrl || safeBaseline.workItemUrl,
             };
-        });
+        }));
         const summary = rows.reduce((acc, row) => {
             if (row.compareStatus === 'Added')
                 acc.addedCount += 1;