@reportforge/playwright-pdf 0.21.0 → 0.22.0

package/README.md

@@ -208,6 +208,7 @@ All options are the second element of the reporter tuple.
 | `remoteHistory` | `boolean` | `false` | Opt-in server-side trend store so the pass-rate trend survives ephemeral CI runners (the local history file is wiped with the workspace, leaving the chart stuck at one data point). One request per run over the existing license connection carrying aggregate numbers only — no test titles, no error text; the branch name is sent as a hash. Falls back to the local history file on any failure. See the History docs. |
 | `flakinessTopN` | `number` | `5` | Maximum flaky tests to show in the flakiness table (`detailed` template). Set to `0` to disable the table entirely. |
 | `slowTestThreshold` | `number` | `10` | Minimum timed-test count before `SLOW` badges appear in the suite breakdown: below this, every test is trivially the "slowest" so badges stay hidden. On larger runs only genuine outliers (at least 2× the median test duration) are badged, so the badge stays rare. Set to `0` to drop the run-size gate (outliers still required). |
+| `requirementTagPattern` | `string` | `'^@?[A-Z][A-Z0-9]*-\\d+$'` | Regex deciding which tags count as requirement IDs in the Requirements Traceability section (`detailed` template). Matching tags (ticket shapes like `@ODP-5328`, `REQ-001`) get the traceability matrix; everything else (`@regression`, `@sanity`) collapses into a compact tag summary instead of repeating identical rows. Set to `''` to disable the split and list every tag in the matrix. |
 | `templatePath` | `string \| string[]` | n/a | Path to a custom Handlebars (`.hbs`) template file. Takes precedence over `template`. Pass an array to generate one PDF per custom template. See the Custom Templates docs. |
 | `sections` | `object` | per-template | Override which report sections appear, on top of the chosen template's defaults. Flat keys are the baseline for every chosen template; per-template keys (`minimal`\|`detailed`\|`executive`) override per template. Block toggles: `coverPage`, `analysisOneliner`, `releaseGate`, `summary`, `charts`, `trend`, `requirementsMatrix`, `ciEnvironment`, `suiteBreakdown`, `failureDeepDive`, `failureAnalysis`, `slowTests`, `defectLog`, `briefBand`. Display modifiers: `passRate`, `fullEnvironment`, `retries`, `fullFailures`, `stackTraces`. See the Report Sections docs. |
 <!-- AUTOGEN:options-table END -->
@@ -442,7 +443,7 @@ reporter: [['@reportforge/playwright-pdf', {
 | `summary` | KPI strip (total · passed · failed · timed-out · skipped · flaky), verdict, duration, pass rate, flaky callout |
 | `charts` | Pass-rate doughnut + stacked suite-results bar |
 | `trend` | Pass-rate trend line, run-history table, and flakiness table (rendered inside `charts`) |
-| `requirementsMatrix` | Tests grouped by `@tag('REQ-…')` with coverage bars (requirements traceability) |
+| `requirementsMatrix` | Requirement-ID tags as a traceability matrix with pass-rate bars, plus a category tag summary |
 | `ciEnvironment` | Branch, commit, browsers, CI provider, OS, Node, Playwright, projects, workers |
 | `suiteBreakdown` | Per-suite → per-test table (status, duration, tags, retries). Failed tests carry their failure detail, root-cause chip, and a `SLOW` badge inline (the three keys below) |
 | `failureDeepDive` | Inline failure detail under each failed test in the breakdown: error message, stack trace, screenshot, retry history |
@@ -639,14 +640,14 @@ Full lifecycle + offline failure modes: [reportforge.org/docs/licensing](https:/
 
 ## Requirements Traceability
 
-The `detailed` template generates a requirements matrix from test tags. Tag tests to link them to requirements:
+The `detailed` template generates a requirements matrix from test tags. Tag tests with ticket-shaped IDs to link them to requirements:
 
 ```ts
-test('@REQ-101 user can login', async ({ page }) => { /* ... */ });
-test.describe('@FEAT-payment', () => { /* ... */ });
+test('user can login', { tag: ['@REQ-101', '@smoke'] }, async ({ page }) => { /* ... */ });
+test.describe('payment', { tag: '@PAY-204' }, () => { /* ... */ });
 ```
 
-The matrix rolls tests up per tag with pass count, fail count, and coverage percentage.
+Tags matching `requirementTagPattern` (default: ticket shapes like `@REQ-101`, `@ODP-5328`, `JIRA-42`) each get a matrix row — test count, pass/fail counts, and a pass-rate bar — sorted by ID. Category tags (`@smoke`, `@regression`) collapse into a compact tag summary below the matrix instead of repeating one near-identical row per tag. Set `requirementTagPattern: ''` to disable the split and list every tag in the matrix.
 
 ---
 

package/dist/cli/index.js

@@ -95,7 +95,7 @@ var init_stats_utils = __esm({
 });
 
 // src/demo/fixture.ts
-function makeTest(id, title, status, duration, retries = 0) {
+function makeTest(id, title, status, duration, retries = 0, tags = []) {
   return {
     id,
     title,
@@ -103,7 +103,7 @@ function makeTest(id, title, status, duration, retries = 0) {
     status,
     duration,
     retryCount: retries,
-    tags: [],
+    tags,
     annotations: []
   };
 }
@@ -381,20 +381,20 @@ var init_fixture = __esm({
       machineLimit: 25
     };
     DEMO_AUTH_TESTS = [
-      makeTest("auth-1", "should login with valid credentials", "passed", 1240),
-      makeTest("auth-2", "should show error for wrong password", "passed", 890),
-      makeTest("auth-3", "should require email confirmation", "passed", 1100),
-      makeTest("auth-4", "should handle session timeout gracefully", "flaky", 3200, 1),
-      makeTest("auth-5", "should block brute-force attempts after 5 tries", "failed", 15e3, 2),
-      makeTest("auth-6", "should logout and clear session cookies", "passed", 780)
+      makeTest("auth-1", "should login with valid credentials", "passed", 1240, 0, ["@auth", "@smoke", "@SHOP-1201"]),
+      makeTest("auth-2", "should show error for wrong password", "passed", 890, 0, ["@auth", "@smoke", "@SHOP-1201"]),
+      makeTest("auth-3", "should require email confirmation", "passed", 1100, 0, ["@auth", "@regression", "@SHOP-1188"]),
+      makeTest("auth-4", "should handle session timeout gracefully", "flaky", 3200, 1, ["@auth", "@regression"]),
+      makeTest("auth-5", "should block brute-force attempts after 5 tries", "failed", 15e3, 2, ["@auth", "@regression", "@SHOP-1349"]),
+      makeTest("auth-6", "should logout and clear session cookies", "passed", 780, 0, ["@auth", "@smoke"])
     ];
     DEMO_CHECKOUT_TESTS = [
-      makeTest("co-1", "should add product to cart", "passed", 1050),
-      makeTest("co-2", "should apply valid promo code", "passed", 2100),
-      makeTest("co-3", "should reject expired promo code", "failed", 8e3, 2),
-      makeTest("co-4", "should calculate shipping by region", "passed", 1800),
-      makeTest("co-5", "should complete Stripe checkout", "passed", 4200),
-      makeTest("co-6", "should send order confirmation email", "skipped", 0)
+      makeTest("co-1", "should add product to cart", "passed", 1050, 0, ["@checkout", "@smoke", "@SHOP-1042"]),
+      makeTest("co-2", "should apply valid promo code", "passed", 2100, 0, ["@checkout", "@regression", "@SHOP-1277"]),
+      makeTest("co-3", "should reject expired promo code", "failed", 8e3, 2, ["@checkout", "@regression", "@SHOP-1277"]),
+      makeTest("co-4", "should calculate shipping by region", "passed", 1800, 0, ["@checkout", "@regression"]),
+      makeTest("co-5", "should complete Stripe checkout", "passed", 4200, 0, ["@checkout", "@smoke", "@SHOP-1042"]),
+      makeTest("co-6", "should send order confirmation email", "skipped", 0, 0, ["@checkout"])
     ];
     DEMO_CATALOG_TESTS = [
       makeTest("cat-1", "should display product grid with filters", "passed", 980),
@@ -6362,7 +6362,10 @@ var init_defaults = __esm({
       historySize: 10,
       showTrend: true,
       flakinessTopN: 5,
-      slowTestThreshold: 10
+      slowTestThreshold: 10,
+      // Ticket-ID shape: @ODP-5328, REQ-001, JIRA-123. Tags matching this land in
+      // the Requirements Traceability matrix; the rest fall to the tag summary.
+      requirementTagPattern: "^@?[A-Z][A-Z0-9]*-\\d+$"
     };
   }
 });
@@ -6620,7 +6623,7 @@ function deriveOptions(s) {
     showFullFailures: s.fullFailures
   };
 }
-var import_handlebars, import_fs, import_path, A4_HEIGHT_MM, PAGE_MARGIN_Y_MM, PX_PER_MM, SUITE_CHART_SMALL_MAX, SUITE_CHART_ROWS_PER_CANVAS, SUITE_CHART_ROW_PX, SUITE_CHART_PAD_PX, PAGE_CONTENT_HEIGHT_PX, SLOW_MEDIAN_FACTOR, TemplateEngine;
+var import_handlebars, import_fs, import_path, A4_HEIGHT_MM, PAGE_MARGIN_Y_MM, PX_PER_MM, SUITE_CHART_SMALL_MAX, SUITE_CHART_ROWS_PER_CANVAS, SUITE_CHART_ROW_PX, SUITE_CHART_PAD_PX, PAGE_CONTENT_HEIGHT_PX, NUMERIC_COLLATOR, SLOW_MEDIAN_FACTOR, TemplateEngine;
 var init_engine = __esm({
   "src/templates/engine.ts"() {
     "use strict";
@@ -6640,6 +6643,7 @@ var init_engine = __esm({
     SUITE_CHART_ROW_PX = 18;
     SUITE_CHART_PAD_PX = 56;
     PAGE_CONTENT_HEIGHT_PX = (A4_HEIGHT_MM - 2 * PAGE_MARGIN_Y_MM) * PX_PER_MM;
+    NUMERIC_COLLATOR = new Intl.Collator(void 0, { numeric: true });
     SLOW_MEDIAN_FACTOR = 2;
     TemplateEngine = class {
       constructor() {
@@ -6666,17 +6670,22 @@ var init_engine = __esm({
       setChartjsBundle(inline) {
         this.chartjsInline = inline;
       }
-      render(data, template, userSections, slowTestThreshold) {
+      render(data, template, opts = {}) {
         const layoutPath = import_path.default.join(this.templatesDir, "layouts", `${template}.hbs`);
         if (!import_fs.default.existsSync(layoutPath)) {
           throw new Error(`[reportforge] Template layout not found: ${layoutPath}`);
         }
         const layoutSource = import_fs.default.readFileSync(layoutPath, "utf8");
         const compiledLayout = this.handlebars.compile(layoutSource);
-        const ctx = this.buildContext(data, template, userSections, slowTestThreshold);
+        const ctx = this.assembleContext(
+          data,
+          resolveSections(template, opts.sections),
+          this.readStyle(`${template}.css`),
+          opts
+        );
         return compiledLayout(ctx);
       }
-      renderFromPath(data, filePath, slowTestThreshold) {
+      renderFromPath(data, filePath, opts = {}) {
         if (!this.customTemplateCache.has(filePath)) {
           if (!import_fs.default.existsSync(filePath)) {
             throw new Error(`[reportforge] Custom template not found: ${filePath}`);
@@ -6685,46 +6694,27 @@ var init_engine = __esm({
           this.customTemplateCache.set(filePath, this.handlebars.compile(source));
         }
         const compiledFn = this.customTemplateCache.get(filePath);
-        return compiledFn(this.buildCustomContext(data, slowTestThreshold));
+        return compiledFn(this.assembleContext(data, allSectionsOn(), "", opts));
       }
-      buildCustomContext(data, slowTestThreshold) {
-        const sections = allSectionsOn();
-        const slow = this.buildSlowTests(data);
-        return {
-          ...data,
-          projects: this.enrichProjects(data, slow, sections, slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold),
-          options: deriveOptions(sections),
-          sections,
-          tagGroups: this.buildTagGroups(data),
-          slowTests: slow.ranked,
-          baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
-          templateCSS: "",
-          chartjsScript: this.buildChartjsScript(),
-          watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
-          releaseGateTally: buildFailureTally(data.analysis),
-          suiteChartLarge: data.charts.suiteResults.length > SUITE_CHART_SMALL_MAX,
-          suiteChartChunks: data.charts.suiteResults.length > SUITE_CHART_SMALL_MAX ? buildSuiteChartChunks(data.charts.suiteResults) : []
-        };
-      }
-      buildContext(data, template, userSections, slowTestThreshold) {
-        const baseCSS = this.fontsBundleCss + "\n" + this.readStyle("base.css");
-        const templateCSS = this.readStyle(`${template}.css`);
-        const sections = resolveSections(template, userSections);
+      assembleContext(data, sections, templateCSS, opts) {
         const options = deriveOptions(sections);
         const slow = this.buildSlowTests(data);
+        const tags = this.buildTagGroups(data, opts.requirementTagPattern);
         return {
           ...data,
           projects: this.enrichProjects(
             data,
             slow,
             sections,
-            slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold
+            opts.slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold
           ),
           options,
           sections,
-          tagGroups: this.buildTagGroups(data),
+          tagGroups: tags.all,
+          requirementTagGroups: tags.requirements,
+          categoryTagGroups: tags.categories,
           slowTests: slow.ranked,
-          baseCSS,
+          baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
           templateCSS,
           chartjsScript: this.buildChartjsScript(),
           watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
@@ -6736,7 +6726,7 @@ var init_engine = __esm({
       buildChartjsScript() {
         return this.chartjsInline ? `<script>${this.chartjsInline}</script>` : "<!-- Chart.js not bundled; charts disabled --><script>window.__chartsReady=true;</script>";
       }
-      buildTagGroups(data) {
+      buildTagGroups(data, requirementTagPattern) {
         const tagMap = /* @__PURE__ */ new Map();
         for (const project of data.projects) {
           for (const suite of this.flattenSuites(project.suites)) {
@@ -6751,11 +6741,20 @@ var init_engine = __esm({
             }
           }
         }
-        return Array.from(tagMap.entries()).map(([tag, counts]) => ({
-          tag,
-          ...counts,
-          coveragePct: counts.total > 0 ? Math.round(counts.passed / counts.total * 100) : 0
-        }));
+        const regex = new RegExp(requirementTagPattern ?? DEFAULT_OPTIONS.requirementTagPattern);
+        const requirements = [];
+        const categories = [];
+        for (const [tag, counts] of tagMap) {
+          const row = {
+            tag,
+            ...counts,
+            coveragePct: counts.total > 0 ? Math.round(counts.passed / counts.total * 100) : 0
+          };
+          (regex.test(tag) ? requirements : categories).push(row);
+        }
+        requirements.sort((a, b) => NUMERIC_COLLATOR.compare(a.tag, b.tag));
+        categories.sort((a, b) => b.total - a.total || a.tag.localeCompare(b.tag));
+        return { all: [...requirements, ...categories], requirements, categories };
       }
       buildSlowTests(data) {
         const tests = [];
@@ -7858,7 +7857,12 @@ var init_PdfGenerator = __esm({
         }
         const templateLabel = source.kind === "builtin" ? source.id : source.label;
         logger.info(`Rendering template: ${templateLabel}`);
-        const html = source.kind === "builtin" ? this.templateEngine.render(renderData, source.id, options.sections, options.slowTestThreshold) : this.templateEngine.renderFromPath(renderData, source.absolutePath, options.slowTestThreshold);
+        const renderOpts = {
+          sections: options.sections,
+          slowTestThreshold: options.slowTestThreshold,
+          requirementTagPattern: options.requirementTagPattern
+        };
+        const html = source.kind === "builtin" ? this.templateEngine.render(renderData, source.id, renderOpts) : this.templateEngine.renderFromPath(renderData, source.absolutePath, renderOpts);
         const tempHtmlPath = await this.htmlWriter.write(html);
         const fileUrl = this.htmlWriter.toFileUrl(tempHtmlPath);
         try {
@@ -12133,6 +12137,14 @@ var init_schema = __esm({
       remoteHistory: external_exports.boolean().default(false),
       flakinessTopN: external_exports.number().int().min(0, "flakinessTopN must be 0 or greater").optional().default(DEFAULT_OPTIONS.flakinessTopN),
       slowTestThreshold: external_exports.number().int().min(0, "slowTestThreshold must be 0 or greater").optional().default(DEFAULT_OPTIONS.slowTestThreshold),
+      requirementTagPattern: external_exports.string().refine((v) => {
+        try {
+          new RegExp(v);
+          return true;
+        } catch {
+          return false;
+        }
+      }, "requirementTagPattern must be a valid regular expression").optional().default(DEFAULT_OPTIONS.requirementTagPattern),
       failureAnalysis: failureAnalysisConfigSchema,
       capture: captureConfigSchema,
       live: liveConfigSchema,

package/dist/index.d.mts

@@ -357,6 +357,17 @@ interface ReporterOptions {
      * @default 10
      */
     slowTestThreshold?: number;
+    /**
+     * Regex (string) deciding which tags count as requirement IDs in the
+     * Requirements Traceability section. Matching tags get the traceability
+     * matrix; the rest collapse into a compact tag summary, so suite-level
+     * category tags (`@regression`, `@sanity`) no longer repeat identical
+     * rows. The default matches ticket-ID shapes such as `@ODP-5328`,
+     * `REQ-001`, or `JIRA-123` (uppercase key, dash, digits). Set to `''` to
+     * disable the split and list every tag in the matrix (legacy behavior).
+     * @default '^@?[A-Z][A-Z0-9]*-\\d+$'
+     */
+    requirementTagPattern?: string;
     /**
      * Path to a custom Handlebars (.hbs) template file. When set, takes
      * precedence over `template`. Relative paths resolve from `process.cwd()`.

package/dist/index.d.ts

@@ -357,6 +357,17 @@ interface ReporterOptions {
      * @default 10
      */
     slowTestThreshold?: number;
+    /**
+     * Regex (string) deciding which tags count as requirement IDs in the
+     * Requirements Traceability section. Matching tags get the traceability
+     * matrix; the rest collapse into a compact tag summary, so suite-level
+     * category tags (`@regression`, `@sanity`) no longer repeat identical
+     * rows. The default matches ticket-ID shapes such as `@ODP-5328`,
+     * `REQ-001`, or `JIRA-123` (uppercase key, dash, digits). Set to `''` to
+     * disable the split and list every tag in the matrix (legacy behavior).
+     * @default '^@?[A-Z][A-Z0-9]*-\\d+$'
+     */
+    requirementTagPattern?: string;
     /**
      * Path to a custom Handlebars (.hbs) template file. When set, takes
      * precedence over `template`. Relative paths resolve from `process.cwd()`.

package/dist/index.js

@@ -10330,7 +10330,10 @@ var DEFAULT_OPTIONS = {
   historySize: 10,
   showTrend: true,
   flakinessTopN: 5,
-  slowTestThreshold: 10
+  slowTestThreshold: 10,
+  // Ticket-ID shape: @ODP-5328, REQ-001, JIRA-123. Tags matching this land in
+  // the Requirements Traceability matrix; the rest fall to the tag summary.
+  requirementTagPattern: "^@?[A-Z][A-Z0-9]*-\\d+$"
 };
 
 // src/templates/sections.ts
@@ -10559,6 +10562,14 @@ var ReporterOptionsSchema = external_exports.object({
   remoteHistory: external_exports.boolean().default(false),
   flakinessTopN: external_exports.number().int().min(0, "flakinessTopN must be 0 or greater").optional().default(DEFAULT_OPTIONS.flakinessTopN),
   slowTestThreshold: external_exports.number().int().min(0, "slowTestThreshold must be 0 or greater").optional().default(DEFAULT_OPTIONS.slowTestThreshold),
+  requirementTagPattern: external_exports.string().refine((v) => {
+    try {
+      new RegExp(v);
+      return true;
+    } catch {
+      return false;
+    }
+  }, "requirementTagPattern must be a valid regular expression").optional().default(DEFAULT_OPTIONS.requirementTagPattern),
   failureAnalysis: failureAnalysisConfigSchema,
   capture: captureConfigSchema,
   live: liveConfigSchema,
@@ -12638,6 +12649,7 @@ var PAGE_CONTENT_HEIGHT_PX = (A4_HEIGHT_MM - 2 * PAGE_MARGIN_Y_MM) * PX_PER_MM;
 function isUnknownValue(v) {
   return !v || v === "unknown";
 }
+var NUMERIC_COLLATOR = new Intl.Collator(void 0, { numeric: true });
 var SLOW_MEDIAN_FACTOR = 2;
 function buildSuiteChartChunks(rows) {
   const chunks = [];
@@ -12687,17 +12699,22 @@ var TemplateEngine = class {
   setChartjsBundle(inline) {
     this.chartjsInline = inline;
   }
-  render(data, template, userSections, slowTestThreshold) {
+  render(data, template, opts = {}) {
     const layoutPath = import_path3.default.join(this.templatesDir, "layouts", `${template}.hbs`);
     if (!import_fs4.default.existsSync(layoutPath)) {
       throw new Error(`[reportforge] Template layout not found: ${layoutPath}`);
     }
     const layoutSource = import_fs4.default.readFileSync(layoutPath, "utf8");
     const compiledLayout = this.handlebars.compile(layoutSource);
-    const ctx = this.buildContext(data, template, userSections, slowTestThreshold);
+    const ctx = this.assembleContext(
+      data,
+      resolveSections(template, opts.sections),
+      this.readStyle(`${template}.css`),
+      opts
+    );
     return compiledLayout(ctx);
   }
-  renderFromPath(data, filePath, slowTestThreshold) {
+  renderFromPath(data, filePath, opts = {}) {
     if (!this.customTemplateCache.has(filePath)) {
       if (!import_fs4.default.existsSync(filePath)) {
         throw new Error(`[reportforge] Custom template not found: ${filePath}`);
@@ -12706,46 +12723,27 @@ var TemplateEngine = class {
       this.customTemplateCache.set(filePath, this.handlebars.compile(source));
     }
     const compiledFn = this.customTemplateCache.get(filePath);
-    return compiledFn(this.buildCustomContext(data, slowTestThreshold));
+    return compiledFn(this.assembleContext(data, allSectionsOn(), "", opts));
   }
-  buildCustomContext(data, slowTestThreshold) {
-    const sections = allSectionsOn();
-    const slow = this.buildSlowTests(data);
-    return {
-      ...data,
-      projects: this.enrichProjects(data, slow, sections, slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold),
-      options: deriveOptions(sections),
-      sections,
-      tagGroups: this.buildTagGroups(data),
-      slowTests: slow.ranked,
-      baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
-      templateCSS: "",
-      chartjsScript: this.buildChartjsScript(),
-      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
-      releaseGateTally: buildFailureTally(data.analysis),
-      suiteChartLarge: data.charts.suiteResults.length > SUITE_CHART_SMALL_MAX,
-      suiteChartChunks: data.charts.suiteResults.length > SUITE_CHART_SMALL_MAX ? buildSuiteChartChunks(data.charts.suiteResults) : []
-    };
-  }
-  buildContext(data, template, userSections, slowTestThreshold) {
-    const baseCSS = this.fontsBundleCss + "\n" + this.readStyle("base.css");
-    const templateCSS = this.readStyle(`${template}.css`);
-    const sections = resolveSections(template, userSections);
+  assembleContext(data, sections, templateCSS, opts) {
     const options = deriveOptions(sections);
     const slow = this.buildSlowTests(data);
+    const tags = this.buildTagGroups(data, opts.requirementTagPattern);
     return {
       ...data,
       projects: this.enrichProjects(
         data,
         slow,
         sections,
-        slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold
+        opts.slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold
       ),
       options,
       sections,
-      tagGroups: this.buildTagGroups(data),
+      tagGroups: tags.all,
+      requirementTagGroups: tags.requirements,
+      categoryTagGroups: tags.categories,
       slowTests: slow.ranked,
-      baseCSS,
+      baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
       templateCSS,
       chartjsScript: this.buildChartjsScript(),
       watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
@@ -12757,7 +12755,7 @@ var TemplateEngine = class {
   buildChartjsScript() {
     return this.chartjsInline ? `<script>${this.chartjsInline}</script>` : "<!-- Chart.js not bundled; charts disabled --><script>window.__chartsReady=true;</script>";
   }
-  buildTagGroups(data) {
+  buildTagGroups(data, requirementTagPattern) {
     const tagMap = /* @__PURE__ */ new Map();
     for (const project of data.projects) {
       for (const suite of this.flattenSuites(project.suites)) {
@@ -12772,11 +12770,20 @@ var TemplateEngine = class {
         }
       }
     }
-    return Array.from(tagMap.entries()).map(([tag, counts]) => ({
-      tag,
-      ...counts,
-      coveragePct: counts.total > 0 ? Math.round(counts.passed / counts.total * 100) : 0
-    }));
+    const regex = new RegExp(requirementTagPattern ?? DEFAULT_OPTIONS.requirementTagPattern);
+    const requirements = [];
+    const categories = [];
+    for (const [tag, counts] of tagMap) {
+      const row = {
+        tag,
+        ...counts,
+        coveragePct: counts.total > 0 ? Math.round(counts.passed / counts.total * 100) : 0
+      };
+      (regex.test(tag) ? requirements : categories).push(row);
+    }
+    requirements.sort((a, b) => NUMERIC_COLLATOR.compare(a.tag, b.tag));
+    categories.sort((a, b) => b.total - a.total || a.tag.localeCompare(b.tag));
+    return { all: [...requirements, ...categories], requirements, categories };
   }
   buildSlowTests(data) {
     const tests = [];
@@ -13533,7 +13540,12 @@ var PdfGenerator = class {
     }
     const templateLabel = source.kind === "builtin" ? source.id : source.label;
     logger.info(`Rendering template: ${templateLabel}`);
-    const html = source.kind === "builtin" ? this.templateEngine.render(renderData, source.id, options.sections, options.slowTestThreshold) : this.templateEngine.renderFromPath(renderData, source.absolutePath, options.slowTestThreshold);
+    const renderOpts = {
+      sections: options.sections,
+      slowTestThreshold: options.slowTestThreshold,
+      requirementTagPattern: options.requirementTagPattern
+    };
+    const html = source.kind === "builtin" ? this.templateEngine.render(renderData, source.id, renderOpts) : this.templateEngine.renderFromPath(renderData, source.absolutePath, renderOpts);
     const tempHtmlPath = await this.htmlWriter.write(html);
     const fileUrl = this.htmlWriter.toFileUrl(tempHtmlPath);
     try {
@@ -14401,7 +14413,7 @@ var PdfReporter = class {
     this.options = parseOptions(rawOptions);
     setLogLevel(this.options.logLevel);
     this.dataCollector = new DataCollector(this.options.capture);
-    this.version = true ? "0.21.0" : "0.x";
+    this.version = true ? "0.22.0" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${this.version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,

package/dist/index.mjs

@@ -10331,7 +10331,10 @@ var DEFAULT_OPTIONS = {
   historySize: 10,
   showTrend: true,
   flakinessTopN: 5,
-  slowTestThreshold: 10
+  slowTestThreshold: 10,
+  // Ticket-ID shape: @ODP-5328, REQ-001, JIRA-123. Tags matching this land in
+  // the Requirements Traceability matrix; the rest fall to the tag summary.
+  requirementTagPattern: "^@?[A-Z][A-Z0-9]*-\\d+$"
 };
 
 // src/templates/sections.ts
@@ -10560,6 +10563,14 @@ var ReporterOptionsSchema = external_exports.object({
   remoteHistory: external_exports.boolean().default(false),
   flakinessTopN: external_exports.number().int().min(0, "flakinessTopN must be 0 or greater").optional().default(DEFAULT_OPTIONS.flakinessTopN),
   slowTestThreshold: external_exports.number().int().min(0, "slowTestThreshold must be 0 or greater").optional().default(DEFAULT_OPTIONS.slowTestThreshold),
+  requirementTagPattern: external_exports.string().refine((v) => {
+    try {
+      new RegExp(v);
+      return true;
+    } catch {
+      return false;
+    }
+  }, "requirementTagPattern must be a valid regular expression").optional().default(DEFAULT_OPTIONS.requirementTagPattern),
   failureAnalysis: failureAnalysisConfigSchema,
   capture: captureConfigSchema,
   live: liveConfigSchema,
@@ -12639,6 +12650,7 @@ var PAGE_CONTENT_HEIGHT_PX = (A4_HEIGHT_MM - 2 * PAGE_MARGIN_Y_MM) * PX_PER_MM;
 function isUnknownValue(v) {
   return !v || v === "unknown";
 }
+var NUMERIC_COLLATOR = new Intl.Collator(void 0, { numeric: true });
 var SLOW_MEDIAN_FACTOR = 2;
 function buildSuiteChartChunks(rows) {
   const chunks = [];
@@ -12688,17 +12700,22 @@ var TemplateEngine = class {
   setChartjsBundle(inline) {
     this.chartjsInline = inline;
   }
-  render(data, template, userSections, slowTestThreshold) {
+  render(data, template, opts = {}) {
     const layoutPath = path9.join(this.templatesDir, "layouts", `${template}.hbs`);
     if (!fs7.existsSync(layoutPath)) {
       throw new Error(`[reportforge] Template layout not found: ${layoutPath}`);
     }
     const layoutSource = fs7.readFileSync(layoutPath, "utf8");
     const compiledLayout = this.handlebars.compile(layoutSource);
-    const ctx = this.buildContext(data, template, userSections, slowTestThreshold);
+    const ctx = this.assembleContext(
+      data,
+      resolveSections(template, opts.sections),
+      this.readStyle(`${template}.css`),
+      opts
+    );
     return compiledLayout(ctx);
   }
-  renderFromPath(data, filePath, slowTestThreshold) {
+  renderFromPath(data, filePath, opts = {}) {
     if (!this.customTemplateCache.has(filePath)) {
       if (!fs7.existsSync(filePath)) {
         throw new Error(`[reportforge] Custom template not found: ${filePath}`);
@@ -12707,46 +12724,27 @@ var TemplateEngine = class {
       this.customTemplateCache.set(filePath, this.handlebars.compile(source));
     }
     const compiledFn = this.customTemplateCache.get(filePath);
-    return compiledFn(this.buildCustomContext(data, slowTestThreshold));
+    return compiledFn(this.assembleContext(data, allSectionsOn(), "", opts));
   }
-  buildCustomContext(data, slowTestThreshold) {
-    const sections = allSectionsOn();
-    const slow = this.buildSlowTests(data);
-    return {
-      ...data,
-      projects: this.enrichProjects(data, slow, sections, slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold),
-      options: deriveOptions(sections),
-      sections,
-      tagGroups: this.buildTagGroups(data),
-      slowTests: slow.ranked,
-      baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
-      templateCSS: "",
-      chartjsScript: this.buildChartjsScript(),
-      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
-      releaseGateTally: buildFailureTally(data.analysis),
-      suiteChartLarge: data.charts.suiteResults.length > SUITE_CHART_SMALL_MAX,
-      suiteChartChunks: data.charts.suiteResults.length > SUITE_CHART_SMALL_MAX ? buildSuiteChartChunks(data.charts.suiteResults) : []
-    };
-  }
-  buildContext(data, template, userSections, slowTestThreshold) {
-    const baseCSS = this.fontsBundleCss + "\n" + this.readStyle("base.css");
-    const templateCSS = this.readStyle(`${template}.css`);
-    const sections = resolveSections(template, userSections);
+  assembleContext(data, sections, templateCSS, opts) {
     const options = deriveOptions(sections);
     const slow = this.buildSlowTests(data);
+    const tags = this.buildTagGroups(data, opts.requirementTagPattern);
     return {
       ...data,
       projects: this.enrichProjects(
         data,
         slow,
         sections,
-        slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold
+        opts.slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold
       ),
       options,
       sections,
-      tagGroups: this.buildTagGroups(data),
+      tagGroups: tags.all,
+      requirementTagGroups: tags.requirements,
+      categoryTagGroups: tags.categories,
       slowTests: slow.ranked,
-      baseCSS,
+      baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
       templateCSS,
       chartjsScript: this.buildChartjsScript(),
       watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
@@ -12758,7 +12756,7 @@ var TemplateEngine = class {
   buildChartjsScript() {
     return this.chartjsInline ? `<script>${this.chartjsInline}</script>` : "<!-- Chart.js not bundled; charts disabled --><script>window.__chartsReady=true;</script>";
   }
-  buildTagGroups(data) {
+  buildTagGroups(data, requirementTagPattern) {
     const tagMap = /* @__PURE__ */ new Map();
     for (const project of data.projects) {
       for (const suite of this.flattenSuites(project.suites)) {
@@ -12773,11 +12771,20 @@ var TemplateEngine = class {
         }
       }
     }
-    return Array.from(tagMap.entries()).map(([tag, counts]) => ({
-      tag,
-      ...counts,
-      coveragePct: counts.total > 0 ? Math.round(counts.passed / counts.total * 100) : 0
-    }));
+    const regex = new RegExp(requirementTagPattern ?? DEFAULT_OPTIONS.requirementTagPattern);
+    const requirements = [];
+    const categories = [];
+    for (const [tag, counts] of tagMap) {
+      const row = {
+        tag,
+        ...counts,
+        coveragePct: counts.total > 0 ? Math.round(counts.passed / counts.total * 100) : 0
+      };
+      (regex.test(tag) ? requirements : categories).push(row);
+    }
+    requirements.sort((a, b) => NUMERIC_COLLATOR.compare(a.tag, b.tag));
+    categories.sort((a, b) => b.total - a.total || a.tag.localeCompare(b.tag));
+    return { all: [...requirements, ...categories], requirements, categories };
   }
   buildSlowTests(data) {
     const tests = [];
@@ -13534,7 +13541,12 @@ var PdfGenerator = class {
     }
     const templateLabel = source.kind === "builtin" ? source.id : source.label;
     logger.info(`Rendering template: ${templateLabel}`);
-    const html = source.kind === "builtin" ? this.templateEngine.render(renderData, source.id, options.sections, options.slowTestThreshold) : this.templateEngine.renderFromPath(renderData, source.absolutePath, options.slowTestThreshold);
+    const renderOpts = {
+      sections: options.sections,
+      slowTestThreshold: options.slowTestThreshold,
+      requirementTagPattern: options.requirementTagPattern
+    };
+    const html = source.kind === "builtin" ? this.templateEngine.render(renderData, source.id, renderOpts) : this.templateEngine.renderFromPath(renderData, source.absolutePath, renderOpts);
     const tempHtmlPath = await this.htmlWriter.write(html);
     const fileUrl = this.htmlWriter.toFileUrl(tempHtmlPath);
     try {
@@ -14402,7 +14414,7 @@ var PdfReporter = class {
     this.options = parseOptions(rawOptions);
     setLogLevel(this.options.logLevel);
     this.dataCollector = new DataCollector(this.options.capture);
-    this.version = true ? "0.21.0" : "0.x";
+    this.version = true ? "0.22.0" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${this.version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,

package/dist/templates/partials/requirements-matrix.hbs

@@ -2,8 +2,10 @@
 <div class="section">
   <h2>Requirements Traceability</h2>
   <p style="font-size:10px;color:var(--text-3);margin-bottom:12px;">
-    Tests grouped by annotation tags. Add <code>@tag('REQ-001')</code> to link tests to requirements.
+    {{#if requirementTagGroups.length}}Tests grouped by requirement ID tags.{{else}}No requirement ID tags found.{{/if}}
+    Add <code>{ tag: '@REQ-001' }</code> to link tests to requirements.
   </p>
+  {{#if requirementTagGroups.length}}
   <table>
     <thead>
       <tr>
@@ -11,13 +13,13 @@
         <th style="width:60px;">Tests</th>
         <th style="width:60px;">Passed</th>
         <th style="width:60px;">Failed</th>
-        <th style="width:120px;">Coverage</th>
+        <th style="width:120px;">Pass Rate</th>
       </tr>
     </thead>
     <tbody>
-      {{#each tagGroups}}
+      {{#each requirementTagGroups}}
       <tr class="no-break">
-        <td><code style="font-size:9.5px;">{{tag}}</code></td>
+        <td><code class="req-matrix__tag" style="font-size:9.5px;">{{tag}}</code></td>
         <td>{{total}}</td>
         <td style="color:var(--pass);font-weight:600;">{{passed}}</td>
         <td style="color:{{#if failed}}var(--fail){{else}}var(--pass){{/if}};font-weight:600;">{{failed}}</td>
@@ -31,5 +33,19 @@
       {{/each}}
     </tbody>
   </table>
+  {{/if}}
+  {{#if categoryTagGroups.length}}
+  <div class="tag-summary no-break">
+    <div class="tag-summary__label">Tag Summary</div>
+    <div class="tag-summary__items">
+      {{#each categoryTagGroups}}
+      <span class="tag-summary__item{{#if failed}} tag-summary__item--fail{{/if}}">
+        <code class="tag-summary__tag">{{tag}}</code>
+        <span class="tag-summary__counts">{{passed}}/{{total}}</span>
+      </span>
+      {{/each}}
+    </div>
+  </div>
+  {{/if}}
 </div>
 {{/if}}

package/dist/templates/styles/base.css

@@ -891,6 +891,29 @@ code {
 .coverage-bar__fill--mid  { background: var(--timeout); }
 .coverage-bar__fill--high { background: var(--pass); }
 
+/* ── Requirements traceability: category tag summary ─────────────────────── */
+/* Non-requirement tags (suite-level categories like @regression) collapse
+   into one compact row list instead of repeating identical matrix rows. */
+.tag-summary {
+  margin-top: 10px; padding-top: 10px;
+  border-top: 1px solid var(--border);
+}
+.tag-summary__label {
+  font-family: 'Inter', system-ui, sans-serif; font-weight: 600;
+  font-size: 8.5px; letter-spacing: 0.8px; text-transform: uppercase;
+  color: var(--text-3); margin-bottom: 4px;
+}
+.tag-summary__items { max-width: 340px; }
+.tag-summary__item {
+  display: flex; justify-content: space-between; align-items: center;
+  padding: 3.5px 2px;
+  border-bottom: 1px solid var(--border);
+}
+.tag-summary__item:last-child { border-bottom: none; }
+.tag-summary__tag { font-size: 9.5px; color: var(--text-1); background: none; border: none; padding: 0; }
+.tag-summary__counts { font-size: 8.5px; font-weight: 600; color: var(--pass); }
+.tag-summary__item--fail .tag-summary__counts { color: var(--fail); }
+
 /* ── Environment table — full ci-environment mode (fullEnvironment), shared ─── */
 .env-table {
   background: var(--surface);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportforge/playwright-pdf",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Playwright Test reporter that generates designed PDF reports: minimal, detailed, and executive templates with CI/CD integrations",
   "license": "Elastic-2.0",
   "author": "ReportForge",