@elisra-devops/docgen-skins 0.23.0 → 0.25.0

package/src/index.ts

@@ -22,9 +22,13 @@ export default class Skins {
   SKIN_TYPE_PARAGRAPH = 'paragraph';
   SKIN_TYPE_COVER_PAGE = 'cover-page';
   SKIN_TYPE_TEST_PLAN = 'test-plan';
+  SKIN_TYPE_TEST_STD = 'test-std';
+  SKIN_TYPE_TEST_STP = 'test-stp';
+  SKIN_TYPE_TEST_STR = 'test-str';
   SKIN_TYPE_SYSTEM_OVERVIEW = 'system-overview';
   SKIN_TYPE_INSTALLATION = 'installation';
   SKIN_TYPE_TEST_REPORTER = 'test-reporter';
+  SKIN_TYPE_TIME_MACHINE = 'time-machine-report';
 
   documentSkin: DocumentSkin = {
     templatePath: '',
@@ -38,6 +42,16 @@ export default class Skins {
     this.skinFormat = skinFormat;
   }
 
+  private resolveSkinTypeAlias(skinType: string) {
+    if (skinType === this.SKIN_TYPE_TEST_STD || skinType === this.SKIN_TYPE_TEST_STP) {
+      return this.SKIN_TYPE_TEST_PLAN;
+    }
+    if (skinType === this.SKIN_TYPE_TEST_STR) {
+      return this.SKIN_TYPE_TABLE_STR;
+    }
+    return skinType;
+  }
+
   async addNewContentToDocumentSkin(
     contentControlTitle: string,
     skinType: string,
@@ -51,8 +65,10 @@ export default class Skins {
   ): Promise<any[]> {
     try {
       let populatedSkin: any[] = [];
+      const isStpTestSkin = skinType === this.SKIN_TYPE_TEST_STP;
+      const normalizedSkinType = this.resolveSkinTypeAlias(skinType);
 
-      switch (skinType) {
+      switch (normalizedSkinType) {
         case this.SKIN_TYPE_TABLE:
           populatedSkin = this.generateQueryBasedTable(data, headerStyles, styles, headingLvl);
 
@@ -84,7 +100,8 @@ export default class Skins {
             styles,
             headingLvl,
             includeAttachments,
-            isFlattened
+            isFlattened,
+            isStpTestSkin ? 1 : 0
           );
           break;
         case this.SKIN_TYPE_SYSTEM_OVERVIEW:
@@ -96,6 +113,9 @@ export default class Skins {
         case this.SKIN_TYPE_TEST_REPORTER:
           populatedSkin = this.generateTestReporter(data, contentControlTitle);
           break;
+        case this.SKIN_TYPE_TIME_MACHINE:
+          populatedSkin = this.generateTimeMachineReport(data, headerStyles, styles, headingLvl);
+          break;
         default:
           throw new Error(`Unknown skinType : ${skinType} - not appended to document skin`);
       }
@@ -415,7 +435,8 @@ export default class Skins {
               undefined,
               undefined,
               false,
-              groupedHeader
+              groupedHeader,
+              true
             );
             traceSkin.push(tableSkin.getJSONTable());
           } else if (errorMessage !== null) {
@@ -441,7 +462,8 @@ export default class Skins {
     styles: StyleOptions,
     headingLvl: number = 0,
     includeAttachments: boolean = true,
-    isFlattened = false
+    isFlattened = false,
+    headingLevelOffset = 0
   ): any[] {
     logger.debug(`Generating testSkin as ${this.skinFormat}`);
     let aggregatedErrors: string[] = [];
@@ -486,10 +508,10 @@ export default class Skins {
                   SuiteStyles,
                   suiteId || 0,
                   testSuite.suiteSkinData.level
-                    ? headingLvl + testSuite.suiteSkinData.level
+                    ? headingLvl + testSuite.suiteSkinData.level + headingLevelOffset
                     : headingLvl
-                    ? headingLvl
-                    : 1
+                    ? headingLvl + headingLevelOffset
+                    : 1 + headingLevelOffset
                 );
                 testSkin.push(testSuiteParagraphSkin.getJSONParagraph());
               }
@@ -515,10 +537,10 @@ export default class Skins {
                   TestCaseStyles,
                   testcase.id || 0,
                   testcase.testCaseHeaderSkinData.level
-                    ? headingLvl + testcase.testCaseHeaderSkinData.level
+                    ? headingLvl + testcase.testCaseHeaderSkinData.level + headingLevelOffset
                     : headingLvl
-                    ? headingLvl
-                    : 1
+                    ? headingLvl + headingLevelOffset
+                    : 1 + headingLevelOffset
                 );
                 testSkin.push(testCaseParagraphSkin.getJSONParagraph());
 
@@ -539,6 +561,23 @@ export default class Skins {
                 let richTextSkin: any[] = testDescriptionParagraph.getJSONRichTextParagraph();
                 testSkin = [...testSkin, ...richTextSkin];
 
+                const additionalTestCaseFields = Array.isArray(testcase.testCaseHeaderSkinData?.fields)
+                  ? testcase.testCaseHeaderSkinData.fields.slice(3)
+                  : [];
+                additionalTestCaseFields.forEach((field: any) => {
+                  const name = String(field?.name || '').trim();
+                  const value = String(field?.value ?? '').trim();
+                  if (!value) return;
+                  const combinedValue = name ? `${name}: ${value}` : value;
+                  const paragraph = new JSONParagraph(
+                    { name: '', value: combinedValue },
+                    styles,
+                    testcase.id || 0,
+                    0
+                  );
+                  testSkin.push(paragraph.getJSONParagraph());
+                });
+
                 if (testcase.testCaseRequirements) {
                   if (testcase.testCaseRequirements.length > 0) {
                     let testDescriptionTitleParagraph = new JSONParagraph(
@@ -759,6 +798,204 @@ export default class Skins {
     }
   }
 
+  private formatTimeMachineDate(value: any): string {
+    if (!value) return '';
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) return String(value);
+    const month = parsed.toLocaleString('en-US', { month: 'long' });
+    const day = String(parsed.getDate()).padStart(2, '0');
+    const year = parsed.getFullYear();
+    const hours = String(parsed.getHours()).padStart(2, '0');
+    const minutes = String(parsed.getMinutes()).padStart(2, '0');
+    return `${month} ${day}, ${year} ${hours}:${minutes}`;
+  }
+
+  private asText(value: any): string {
+    if (value === null || value === undefined) return '';
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+    if (typeof value === 'object') {
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return String(value);
+      }
+    }
+    return String(value);
+  }
+
+  private createParagraphWordObject(value: string, style: StyleOptions, headingLevel = 0) {
+    const paragraph = new JSONParagraph({ name: 'Title', value }, { ...style }, 0, headingLevel);
+    return paragraph.getJSONParagraph();
+  }
+
+  private createTextParagraphWordObject(value: string, style: StyleOptions) {
+    const paragraph = new JSONParagraph({ name: '', value }, { ...style }, 0, 0);
+    return paragraph.getJSONParagraph();
+  }
+
+  private createTableWordObject(rows: any[], headerStyles: StyleOptions, styles: StyleOptions) {
+    if (!Array.isArray(rows) || rows.length === 0) return null;
+    const table = new JSONTable(rows as any, { ...headerStyles }, { ...styles }, 0);
+    return table.getJSONTable();
+  }
+
+  generateTimeMachineReport(
+    data: any,
+    headerStyles: StyleOptions,
+    styles: StyleOptions,
+    headingLvl: number = 1
+  ): any[] {
+    const reportData = data?.compareResult ? data.compareResult : data || {};
+    const queryName = this.asText(data?.queryName || reportData?.queryName || '');
+    const teamProjectName = this.asText(data?.teamProjectName || reportData?.teamProjectName || '');
+    const baselineAsOf = reportData?.baseline?.asOf || '';
+    const compareToAsOf = reportData?.compareTo?.asOf || '';
+    const baselineTotal = Number(reportData?.baseline?.total || 0);
+    const compareToTotal = Number(reportData?.compareTo?.total || 0);
+    const summary = reportData?.summary || {};
+    const updatedCount = Number(summary?.updatedCount || 0);
+    const rows = Array.isArray(reportData?.rows) ? reportData.rows : [];
+    const changedRows = rows.filter((row) => String(row?.compareStatus || '').toLowerCase() === 'changed');
+
+    const titleStyles: StyleOptions = {
+      ...styles,
+      isBold: true,
+      InsertLineBreak: false,
+      InsertSpace: false,
+    };
+    const normalStyles: StyleOptions = {
+      ...styles,
+      isBold: false,
+      InsertLineBreak: false,
+      InsertSpace: false,
+    };
+    const tableHeaderStyles: StyleOptions = {
+      ...headerStyles,
+      isBold: true,
+      InsertLineBreak: false,
+      InsertSpace: false,
+    };
+
+    const reportWordObjects: any[] = [];
+    reportWordObjects.push(this.createParagraphWordObject('Difference', titleStyles, Math.max(1, headingLvl)));
+    reportWordObjects.push(
+      this.createTextParagraphWordObject(`Project: ${teamProjectName || 'N/A'}`, normalStyles),
+    );
+    if (queryName) {
+      reportWordObjects.push(this.createTextParagraphWordObject(`Query: ${queryName}`, normalStyles));
+    }
+
+    const compareSummaryTableRows = [
+      {
+        url: '',
+        fields: [
+          { name: 'Point', value: 'Baseline', width: '20%' },
+          { name: 'Time', value: this.formatTimeMachineDate(baselineAsOf), width: '50%' },
+          { name: '# Sum of Work-Items', value: String(baselineTotal), width: '30%' },
+        ],
+        Source: 0,
+        level: 0,
+      },
+      {
+        url: '',
+        fields: [
+          { name: 'Point', value: 'Compare to', width: '20%' },
+          { name: 'Time', value: this.formatTimeMachineDate(compareToAsOf), width: '50%' },
+          { name: '# Sum of Work-Items', value: String(compareToTotal), width: '30%' },
+        ],
+        Source: 0,
+        level: 0,
+      },
+    ];
+    const compareSummaryTable = this.createTableWordObject(compareSummaryTableRows, tableHeaderStyles, normalStyles);
+    if (compareSummaryTable) {
+      reportWordObjects.push(compareSummaryTable);
+    }
+
+    reportWordObjects.push(this.createParagraphWordObject('Summarize', titleStyles, Math.max(1, headingLvl + 2)));
+    reportWordObjects.push(
+      this.createTextParagraphWordObject(`# Sum of Work-Items updated: ${updatedCount}`, normalStyles),
+    );
+
+    if (rows.length > 0) {
+      const compareRows = rows.map((row) => ({
+        url: row?.workItemUrl || '',
+        fields: [
+          { name: 'ID', value: this.asText(row?.id), url: row?.workItemUrl || '', width: '9%' },
+          { name: 'Work Item Type', value: this.asText(row?.workItemType), width: '14%' },
+          { name: 'Title', value: this.asText(row?.title), width: '34%' },
+          { name: 'Id Revision of Baseline', value: this.asText(row?.baselineRevisionId), width: '14%' },
+          { name: 'Id Revision of CompareTo', value: this.asText(row?.compareToRevisionId), width: '14%' },
+          { name: 'Compare Status', value: this.asText(row?.compareStatus), width: '15%' },
+        ],
+        Source: Number(row?.id || 0),
+        level: 0,
+      }));
+      const compareTable = this.createTableWordObject(compareRows, tableHeaderStyles, normalStyles);
+      if (compareTable) {
+        reportWordObjects.push(compareTable);
+      }
+    } else {
+      reportWordObjects.push(this.createTextParagraphWordObject('No work-items were returned.', normalStyles));
+    }
+
+    reportWordObjects.push(
+      this.createParagraphWordObject('2. Work Item Differences', titleStyles, Math.max(1, headingLvl + 2)),
+    );
+    if (changedRows.length === 0) {
+      reportWordObjects.push(
+        this.createTextParagraphWordObject(
+          'No work-items were marked as Changed between the selected date-times.',
+          normalStyles,
+        ),
+      );
+      return reportWordObjects;
+    }
+
+    changedRows.forEach((row) => {
+      const baselineRevision = this.asText(row?.baselineRevisionId || '');
+      const compareRevision = this.asText(row?.compareToRevisionId || '');
+      const differences = Array.isArray(row?.differences) ? row.differences : [];
+      const itemTitle = `${this.asText(row?.workItemType)} ${this.asText(row?.id)} Changed between version ${baselineRevision} and ${compareRevision}`;
+      reportWordObjects.push(
+        this.createParagraphWordObject(itemTitle.trim(), titleStyles, Math.max(1, headingLvl + 3)),
+      );
+      if (differences.length === 0) {
+        reportWordObjects.push(this.createTextParagraphWordObject('No field differences found.', normalStyles));
+        return;
+      }
+
+      differences.forEach((diff) => {
+        reportWordObjects.push(
+          this.createTextParagraphWordObject(`${this.asText(diff?.field)}:`, {
+            ...normalStyles,
+            isBold: true,
+          }),
+        );
+        const baselineValue = [baselineRevision, this.asText(diff?.baseline)].filter(Boolean).join(' ');
+        const compareValue = [compareRevision, this.asText(diff?.compareTo)].filter(Boolean).join(' ');
+        const diffTableRows = [
+          {
+            url: '',
+            fields: [
+              { name: 'Baseline', value: baselineValue, width: '50%' },
+              { name: 'Compare to', value: compareValue, width: '50%' },
+            ],
+            Source: Number(row?.id || 0),
+            level: 0,
+          },
+        ];
+        const diffTable = this.createTableWordObject(diffTableRows, tableHeaderStyles, normalStyles);
+        if (diffTable) {
+          reportWordObjects.push(diffTable);
+        }
+      });
+    });
+
+    return reportWordObjects;
+  }
+
   getDocumentSkin(): DocumentSkin {
     return this.documentSkin;
   } //getDocumentSkin

package/src/models/json/JSONRun.ts

@@ -49,6 +49,7 @@ export default class JSONRun {
           run.InsertLineBreak = style.InsertLineBreak;
         }
         run.InsertSpace = style.InsertSpace;
+        run.SectionRefId = style.SectionRefId || null;
         runs.push(JSON.parse(JSON.stringify(run)));
       });
     } catch (e) {
@@ -67,6 +68,7 @@ export default class JSONRun {
       runs[0].Font = style.Font;
       runs[0].InsertLineBreak = style.InsertLineBreak;
       runs[0].InsertSpace = style.InsertSpace;
+      runs[0].SectionRefId = style.SectionRefId || null;
     }
 
     return runs;

package/src/models/json/paragraph/JSONTestSuiteHeaderParagraph.ts

@@ -30,6 +30,10 @@ export default class JSONTestSuiteHeaderParagraph {
     } else {
       this.paragraphTemplate.headingLevel = 0;
     }
+
+    if (this.wiId) {
+      this.paragraphTemplate.bookmarkName = `_WI${this.wiId}`;
+    }
   } //constructor
 
   generateJsonParagraphHeaderRuns(fields, paragraphStyles) {

package/src/models/json/table/JSONTable.ts

@@ -12,6 +12,7 @@ import JSONTableRow from './JSONTableRow';
 export default class JSONTable {
   tableTemplate: Table;
   tableStyles: StyleOptions;
+  private readonly enableVerticalMerge: boolean;
 
   constructor(
     data: WIQueryResults,
@@ -29,8 +30,10 @@ export default class JSONTable {
       shading?: Shading;
       leftShading?: Shading;
       rightShading?: Shading;
-    }
+    },
+    enableVerticalMerge: boolean = false
   ) {
+    this.enableVerticalMerge = enableVerticalMerge;
     this.tableStyles = tableStyles;
     this.tableTemplate = {
       type: 'table',
@@ -106,8 +109,10 @@ export default class JSONTable {
       rows.push(row.getRow());
     });
 
-    // Apply vertical merging for grouped source cells (first row shows value; subsequent are empty)
-    this.applyVerticalMerges(rows);
+    if (this.enableVerticalMerge) {
+      // Apply vertical merging for grouped source cells (first row shows value; subsequent are empty)
+      this.applyVerticalMerges(rows);
+    }
 
     return rows;
   } //generateJsonRows
@@ -179,6 +184,17 @@ export default class JSONTable {
 
     const getCellText = (cell: any): string => {
       try {
+        const htmlRaw = String(cell?.Html?.Html || '').trim();
+        if (htmlRaw) {
+          const htmlText = htmlRaw
+            .replace(/<[^>]*>/g, ' ')
+            .replace(/&nbsp;/gi, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+          if (htmlText) {
+            return htmlText;
+          }
+        }
         const runs = cell?.Paragraphs?.[0]?.Runs || [];
         return runs.map((r: any) => (r?.text ?? '')).join('').trim();
       } catch {

package/src/models/json/table/JSONTableCell.ts

@@ -87,6 +87,7 @@ export default class JSONTableCell {
         HtmlData = data.value || '';
       } else {
         styles.Uri = data.relativeUrl ? data.relativeUrl : data.url ? data.url : null;
+        styles.SectionRefId = data.sectionRefId ?? null;
         let text = data.value || '';
         let jsonRun = new JSONRun(`${text}`, styles);
         runs = [...runs, ...jsonRun.getRun()];

package/src/models/json/wordJsonModels.ts

@@ -8,6 +8,7 @@ export interface StyleOptions {
   InsertLineBreak: boolean;
   InsertSpace: boolean;
   InsertPageBreak?: boolean;
+  SectionRefId?: string;
 }
 export interface DocumentSkin {
   templatePath: string;
@@ -51,6 +52,7 @@ export interface Paragraph {
   type: string;
   headingLevel?: number;
   runs: Run[];
+  bookmarkName?: string;
 }
 export interface Attachment {
   type: string;
@@ -73,6 +75,7 @@ export interface Run {
   InsertSpace: boolean;
   InsertPageBreak?: boolean;
   src?: string; //for image
+  SectionRefId?: string;
 }
 export interface WorkItemData {}
 
@@ -149,6 +152,7 @@ export interface WIProperty {
   includeAttachmentContent?: boolean;
   relativeAttachmentLink?: string;
   richText?: any[];
+  sectionRefId?: string;
 }
 export interface MultipeValuesWIProperty {
   name: string;
@@ -162,6 +166,7 @@ export interface MultipeValuesWIProperty {
   includeAttachmentContent?: boolean;
   relativeAttachmentLink?: string;
   richText?: any[];
+  sectionRefId?: string;
 }
 export interface WIColumns {
   name: string;

package/src/test/JSONFile.test.ts

@@ -0,0 +1,59 @@
+import JSONFile from '../models/json/file/JSONFile';
+import logger from '../services/logger';
+
+jest.mock('../services/logger', () => ({
+  __esModule: true,
+  default: {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+const getMockLogger = () =>
+  logger as unknown as {
+    debug: jest.Mock;
+    info: jest.Mock;
+    warn: jest.Mock;
+    error: jest.Mock;
+  };
+
+describe('JSONFile', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test('removeFileExtension returns original name when there is no dot', () => {
+    const data: any = {
+      attachmentLink: 'http://server/file',
+      attachmentFileName: 'file',
+      attachmentType: 'asEmbedded',
+      includeAttachmentContent: true,
+    };
+
+    const jsonFile = new JSONFile(data);
+    const attachment = jsonFile.getFileAttachment as any;
+
+    expect(attachment.type).toBe('File');
+    expect(attachment.name).toBe('file');
+  });
+
+  test('isPictureUri handles invalid uri and logs error', () => {
+    const data: any = {
+      attachmentLink: undefined,
+      attachmentFileName: 'file.docx',
+      attachmentType: 'asEmbedded',
+      includeAttachmentContent: true,
+    };
+
+    const jsonFile = new JSONFile(data);
+    const attachment = jsonFile.getFileAttachment as any;
+
+    expect(attachment.type).toBe('File');
+    expect(attachment.name).toBe('file');
+    expect(getMockLogger().error).toHaveBeenCalledWith(
+      expect.stringContaining('error parsing file extension for')
+    );
+  });
+});

package/src/test/JSONRun.test.ts

@@ -0,0 +1,118 @@
+import JSONRun from '../models/json/JSONRun';
+import { defaultJsonRun } from '../models/json/default';
+import logger from '../services/logger';
+
+jest.mock('../services/logger', () => ({
+  __esModule: true,
+  default: {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    silly: jest.fn(),
+  },
+}));
+
+const getMockLogger = () =>
+  logger as unknown as {
+    debug: jest.Mock;
+    info: jest.Mock;
+    warn: jest.Mock;
+    error: jest.Mock;
+    silly: jest.Mock;
+  };
+
+const baseStyles = {
+  isBold: true,
+  IsItalic: false,
+  IsUnderline: false,
+  Size: 12,
+  Uri: 'http://example.com',
+  Font: 'Arial',
+  InsertLineBreak: false,
+  InsertSpace: true,
+  InsertPageBreak: false as boolean | undefined,
+};
+
+describe('JSONRun', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test('splits multi-line text into separate runs with correct line breaks', () => {
+    const value = 'line1\nline2\nline3';
+
+    const jsonRun = new JSONRun(value, { ...baseStyles });
+    const runs = jsonRun.getRun();
+
+    expect(runs).toHaveLength(3);
+
+    expect(runs[0].InsertLineBreak).toBe(true);
+    expect(runs[1].InsertLineBreak).toBe(true);
+    expect(runs[2].InsertLineBreak).toBe(baseStyles.InsertLineBreak);
+
+    runs.forEach((r) => {
+      expect(r.Bold).toBe(baseStyles.isBold);
+      expect(r.Italic).toBe(baseStyles.IsItalic);
+      expect(r.Underline).toBe(baseStyles.IsUnderline);
+      expect(r.Size).toBe(baseStyles.Size);
+      expect(r.Font).toBe(baseStyles.Font);
+      expect(r.InsertSpace).toBe(baseStyles.InsertSpace);
+    });
+  });
+
+  test('uses striphtml replaceBr callback to convert <br> to newline', () => {
+    const value = 'Hello<br>World';
+
+    const jsonRun = new JSONRun(value, { ...baseStyles });
+    const runs = jsonRun.getRun();
+
+    expect(runs).toHaveLength(1);
+    expect(runs[0].text).toContain('\n');
+  });
+
+  test('sets Uri to null when default run Uri is empty string in normal flow', () => {
+    const prevUri = defaultJsonRun.Uri;
+    defaultJsonRun.Uri = '' as any;
+
+    const jsonRun = new JSONRun('plain text', { ...baseStyles });
+    const runs = jsonRun.getRun();
+
+    runs.forEach((r) => {
+      expect(r.Uri).toBeNull();
+    });
+
+    defaultJsonRun.Uri = prevUri;
+  });
+
+  test('does not strip HTML when fieldtype is SuiteHeaderParagraphTitle', () => {
+    const value = '<b>Bold Title</b>';
+
+    const jsonRun = new JSONRun(value, { ...baseStyles }, 'SuiteHeaderParagraphTitle');
+    const runs = jsonRun.getRun();
+
+    expect(runs).toHaveLength(1);
+    expect(runs[0].text).toContain('<b>Bold Title</b>');
+  });
+
+  test('falls back to default run and logs when value cannot be split', () => {
+    const badValue: any = null;
+
+    const prevUri = defaultJsonRun.Uri;
+    defaultJsonRun.Uri = '' as any;
+
+    const jsonRun = new JSONRun(badValue, { ...baseStyles });
+    const runs = jsonRun.getRun();
+
+    expect(getMockLogger().silly).toHaveBeenCalled();
+    expect(runs).toHaveLength(1);
+    expect(runs[0].text).toBe('');
+    expect(runs[0].Bold).toBe(baseStyles.isBold);
+    expect(runs[0].Italic).toBe(baseStyles.IsItalic);
+    expect(runs[0].Underline).toBe(baseStyles.IsUnderline);
+    expect(runs[0].Size).toBe(baseStyles.Size);
+    expect(runs[0].Uri).toBeNull();
+
+    defaultJsonRun.Uri = prevUri;
+  });
+});