gha-workflow-testing 1.0.0 → 1.1.1

package/src/reusable_reporter.ts

@@ -0,0 +1,890 @@
+/**
+ * reusable_reporter.ts
+ *
+ * Aggregating reporter that groups GitHub Actions jobs and steps by the
+ * reusable workflow that defined them. Extends WorkflowTestReporter from
+ * reporter.ts so all existing recording/assertion helpers still work; this
+ * file only adds the aggregation and grouped-output layer on top.
+ *
+ * Primary strategy  : use the `workflow_name` field returned by the GitHub
+ *                     Jobs API (populated when a job is defined in a reusable
+ *                     workflow called via `uses:`).
+ * Fallback strategy : parse the job name for a " / " separator pattern that
+ *                     GitHub sometimes uses when nesting reusable calls
+ *                     (e.g. "call-ci-scan / sonarqube" → group "call-ci-scan").
+ */
+
+import * as fs from 'fs';
+import { WorkflowTestReporter } from './reporter';
+import { GitHubAPI, Jobs } from './github-api';
+
+// ---------------------------------------------------------------------------
+// Interfaces
+// ---------------------------------------------------------------------------
+
+export interface ReusableStepSummary {
+  conclusion: string | null;
+  passed: boolean;
+}
+
+export interface ReusableJobSummary {
+  conclusion: string | null;
+  passed: boolean;
+  steps: { [stepName: string]: ReusableStepSummary };
+}
+
+/** Sentinel group key for jobs defined directly in the caller workflow (not via `uses:`). */
+export const DIRECT_JOBS_GROUP = '(caller)';
+
+export interface ReusableWorkflowGroup {
+  /**
+   * Reusable workflow name (from the `workflow_name` API field, e.g. "scan" / "ci-scan"),
+   * OR `DIRECT_JOBS_GROUP` for jobs defined directly in the caller workflow.
+   */
+  workflowName: string;
+  /**
+   * True when this group holds jobs defined directly in the caller workflow
+   * (not triggered via a reusable workflow `uses:` call).
+   */
+  isDirect: boolean;
+  /**
+   * The caller-workflow job names that invoked this reusable workflow
+   * (e.g. `["call-ci-scan"]`). Empty for direct-job groups.
+   */
+  callerJobNames: string[];
+  jobs: { [jobName: string]: ReusableJobSummary };
+  overallResult: 'success' | 'failure' | 'partial_failure' | 'skipped' | 'unknown';
+  totalJobs: number;
+  passedJobs: number;
+  failedJobs: number;
+  totalSteps: number;
+  passedSteps: number;
+  failedSteps: number;
+}
+
+// ---------------------------------------------------------------------------
+// ReusableWorkflowReporter
+// ---------------------------------------------------------------------------
+
+export class ReusableWorkflowReporter extends WorkflowTestReporter {
+  private callerWorkflowName: string;
+  private reusableGroups: { [wfName: string]: ReusableWorkflowGroup } = {};
+
+  constructor(workflowName: string) {
+    super(workflowName);
+    this.callerWorkflowName = workflowName;
+  }
+
+  // -------------------------------------------------------------------------
+  // Loading & grouping
+  // -------------------------------------------------------------------------
+
+  /**
+   * Convenience method: loads all jobs/steps via the parent's
+   * `loadAllJobsAndSteps`, then groups them by reusable workflow name.
+   */
+  async loadAndGroup(api: GitHubAPI, runId: number): Promise<void> {
+    this.setRunId(runId);
+    await this.loadAllJobsAndSteps(api);
+    await this.groupByReusableWorkflow(api, runId);
+  }
+
+  /**
+   * Fetch all jobs for `runId`, then for each job:
+   *   1. Determine which reusable workflow group it belongs to
+   *      (via `workflow_name` API field, falling back to the job-name pattern).
+   *   2. Fetch its steps and record pass/fail per step.
+   * Builds the internal `reusableGroups` map and computes per-group totals.
+   */
+  async groupByReusableWorkflow(api: GitHubAPI, runId: number): Promise<void> {
+    const jobs: Jobs = await api.getJobs(runId);
+    this.reusableGroups = {};
+
+    for (const [jobName, jobInfo] of Object.entries(jobs)) {
+      // A job is from a reusable workflow call when its name contains " / "
+      // (GitHub names reusable-job as "<caller-job> / <reusable-job>").
+      const slashIdx = jobName.lastIndexOf(' / ');
+      const isReusable = slashIdx !== -1;
+      const callerJobName = isReusable ? jobName.substring(0, slashIdx) : '';
+
+      // Determine the group key:
+      //  • Reusable jobs  → normalised workflow_name (e.g. "scan") or caller-job prefix
+      //  • Direct jobs    → DIRECT_JOBS_GROUP sentinel
+      let groupKey: string;
+      if (!isReusable) {
+        groupKey = DIRECT_JOBS_GROUP;
+      } else if (jobInfo.workflowName) {
+        groupKey = this.normaliseWorkflowName(jobInfo.workflowName);
+      } else {
+        groupKey = callerJobName; // fallback: use the caller job name as group label
+      }
+
+      // Ensure the group exists
+      if (!this.reusableGroups[groupKey]) {
+        this.reusableGroups[groupKey] = {
+          workflowName: groupKey,
+          isDirect: groupKey === DIRECT_JOBS_GROUP,
+          callerJobNames: [],
+          jobs: {},
+          overallResult: 'unknown',
+          totalJobs: 0,
+          passedJobs: 0,
+          failedJobs: 0,
+          totalSteps: 0,
+          passedSteps: 0,
+          failedSteps: 0,
+        };
+      }
+
+      // Track which caller jobs invoke this reusable group (dedup)
+      if (isReusable && callerJobName &&
+          !this.reusableGroups[groupKey].callerJobNames.includes(callerJobName)) {
+        this.reusableGroups[groupKey].callerJobNames.push(callerJobName);
+      }
+
+      const group = this.reusableGroups[groupKey];
+
+      // Fetch steps for this job
+      const stepsMap: { [stepName: string]: ReusableStepSummary } = {};
+      try {
+        const steps = await api.getSteps(runId, jobName);
+        for (const [stepName, stepInfo] of Object.entries(steps)) {
+          const passed =
+            stepInfo.conclusion === 'success' || stepInfo.conclusion === 'skipped';
+          stepsMap[stepName] = { conclusion: stepInfo.conclusion, passed };
+          group.totalSteps++;
+          if (passed) group.passedSteps++;
+          else group.failedSteps++;
+        }
+      } catch {
+        // Steps unavailable for this job — continue without them
+      }
+
+      const jobPassed =
+        jobInfo.conclusion === 'success' || jobInfo.conclusion === 'skipped';
+
+      group.jobs[jobName] = {
+        conclusion: jobInfo.conclusion,
+        passed: jobPassed,
+        steps: stepsMap,
+      };
+      group.totalJobs++;
+      if (jobPassed) group.passedJobs++;
+      else group.failedJobs++;
+    }
+
+    // Compute per-group overall result
+    for (const group of Object.values(this.reusableGroups)) {
+      if (group.totalJobs === 0) {
+        group.overallResult = 'unknown';
+      } else if (group.failedJobs === 0) {
+        group.overallResult = 'success';
+      } else if (group.failedJobs === group.totalJobs) {
+        group.overallResult = 'failure';
+      } else {
+        group.overallResult = 'partial_failure';
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Helpers
+  // -------------------------------------------------------------------------
+
+  /** Return all computed groups (read-only snapshot). */
+  getReusableGroups(): Readonly<{ [wfName: string]: ReusableWorkflowGroup }> {
+    return this.reusableGroups;
+  }
+
+  // -------------------------------------------------------------------------
+  // Built-in assertions
+  // These keep all enumeration logic inside the reporter so tests stay thin.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Assert every reusable-workflow group (excludes the `(caller)` direct-job
+   * group) has `overallResult === 'success'`.
+   * Throws with a summary of every failing group.
+   */
+  assertAllGroupsSucceed(): void {
+    const failures: string[] = [];
+    for (const [name, group] of Object.entries(this.reusableGroups)) {
+      if (group.isDirect) continue; // caller jobs are checked separately
+      if (group.overallResult !== 'success') {
+        const failedJobs = Object.entries(group.jobs)
+          .filter(([, j]) => !j.passed)
+          .map(([jName, j]) => `    job "${jName}": ${j.conclusion}`)
+          .join('\n');
+        failures.push(`group "${name}" → ${group.overallResult}\n${failedJobs}`);
+      }
+    }
+    if (failures.length) throw new Error(`Reusable groups failed:\n${failures.join('\n')}`);
+  }
+
+  /**
+   * Assert every direct (caller-defined) job succeeded.
+   * Throws with the list of failed jobs.
+   */
+  assertAllDirectJobsSucceed(): void {
+    const direct = this.reusableGroups[DIRECT_JOBS_GROUP];
+    if (!direct) return; // no direct jobs — nothing to assert
+    const failures = Object.entries(direct.jobs)
+      .filter(([, j]) => !j.passed)
+      .map(([name, j]) => `  job "${name}": ${j.conclusion}`);
+    if (failures.length)
+      throw new Error(`Direct caller jobs failed:\n${failures.join('\n')}`);
+  }
+
+  /**
+   * Assert every step in every reusable group has an acceptable conclusion
+   * (`'success'` or `'skipped'`).
+   * Throws with a full list of offending steps.
+   */
+  assertAllStepsAcceptable(): void {
+    const acceptable = new Set(['success', 'skipped']);
+    const failures: string[] = [];
+    for (const [groupName, group] of Object.entries(this.reusableGroups)) {
+      for (const [jobName, job] of Object.entries(group.jobs)) {
+        const displayJob = jobName.includes(' / ')
+          ? jobName.substring(jobName.lastIndexOf(' / ') + 3)
+          : jobName;
+        for (const [stepName, step] of Object.entries(job.steps)) {
+          if (!acceptable.has(step.conclusion ?? '')) {
+            failures.push(
+              `[${groupName}] ${displayJob} → "${stepName}": ${step.conclusion}`
+            );
+          }
+        }
+      }
+    }
+    if (failures.length)
+      throw new Error(`Steps with unacceptable conclusions:\n${failures.join('\n')}`);
+  }
+
+  /**
+   * Assert that a reusable-workflow group with the given name (case-insensitive
+   * substring match) exists and succeeded.
+   *
+   * @param pattern  Substring or regex to match against group names
+   *                 (e.g. `'sonar'`, `'snyk'`, `/ci-scan/i`).
+   */
+  assertGroupSucceeds(pattern: string | RegExp): void {
+    const re = typeof pattern === 'string' ? new RegExp(pattern, 'i') : pattern;
+    const match = Object.values(this.reusableGroups).find(
+      (g) => !g.isDirect && re.test(g.workflowName)
+    );
+    if (!match)
+      throw new Error(
+        `No reusable-workflow group matching ${re} found. ` +
+          `Available: ${Object.keys(this.reusableGroups).filter((k) => k !== DIRECT_JOBS_GROUP).join(', ')}`
+      );
+    if (match.overallResult !== 'success') {
+      const failedJobs = Object.entries(match.jobs)
+        .filter(([, j]) => !j.passed)
+        .map(([n, j]) => `  job "${n}": ${j.conclusion}`)
+        .join('\n');
+      throw new Error(
+        `Group "${match.workflowName}" did not succeed (${match.overallResult}):\n${failedJobs}`
+      );
+    }
+  }
+
+  /**
+   * Strip the `.yml` / `.yaml` suffix and owner prefix so the group key is
+   * a short, readable workflow name (e.g. "ci-scan" not "ci-scan.yml").
+   */
+  private normaliseWorkflowName(raw: string): string {
+    // Remove trailing .yml / .yaml
+    return raw.replace(/\.ya?ml$/, '');
+  }
+
+  /**
+   * Fallback: if the job name contains " / ", treat everything before the
+   * last " / " as the group (the caller job name).
+   * Example: "call-ci-scan / sonarqube" → "call-ci-scan"
+   * If no separator, the job itself is its own group.
+   */
+  private inferGroupFromJobName(jobName: string): string {
+    // Use the FIRST segment — convention is "<reusable-wf-name> / <job> / ..."
+    const idx = jobName.indexOf(' / ');
+    return idx !== -1 ? jobName.substring(0, idx) : jobName;
+  }
+
+  // -------------------------------------------------------------------------
+  // Report generation
+  // -------------------------------------------------------------------------
+
+  /** Build a markdown string grouped by reusable workflow. */
+  generateGroupedMarkdown(): string {
+    const lines: string[] = [];
+
+    lines.push('# 🔄 Reusable Workflow Aggregated Test Report');
+    lines.push('');
+    lines.push(`**Caller workflow:** \`${this.callerWorkflowName}\``);
+    lines.push('');
+
+    // Separate direct-caller groups from reusable-WF groups for the overview
+    const directGroup = this.reusableGroups[DIRECT_JOBS_GROUP];
+    const reusableEntries = Object.entries(this.reusableGroups).filter(
+      ([k]) => k !== DIRECT_JOBS_GROUP
+    );
+
+    // ── Top-level overview table (reusable WFs only) ───────────────────────
+    lines.push('## 📊 Reusable Workflow Groups');
+    lines.push('');
+    lines.push(
+      '| Reusable Workflow | Triggered by | Result | Jobs (✅/❌/total) | Steps (✅/❌/total) |'
+    );
+    lines.push(
+      '|-------------------|--------------|--------|-------------------|---------------------|'
+    );
+
+    for (const [, group] of reusableEntries) {
+      const icon = this.resultIcon(group.overallResult);
+      const callerLabel = group.callerJobNames.length
+        ? group.callerJobNames.map((n) => `\`${n}\``).join(', ')
+        : '—';
+      lines.push(
+        `| \`${group.workflowName}\` | ${callerLabel} | ${icon} ${group.overallResult} ` +
+          `| ${group.passedJobs} / ${group.failedJobs} / ${group.totalJobs} ` +
+          `| ${group.passedSteps} / ${group.failedSteps} / ${group.totalSteps} |`
+      );
+    }
+    lines.push('');
+
+    // ── Direct caller jobs summary (if any) ───────────────────────────────
+    if (directGroup) {
+      const icon = this.resultIcon(directGroup.overallResult);
+      lines.push('## 🔧 Direct Caller Jobs');
+      lines.push('');
+      lines.push(
+        `> Jobs defined directly in the caller workflow (not via a reusable \`uses:\` call). ` +
+          `Overall: ${icon} **${directGroup.overallResult}**`
+      );
+      lines.push('');
+      lines.push('| Job | Conclusion | Steps ✅ | Steps ❌ |');
+      lines.push('|-----|-----------|---------|---------|');
+      for (const [jobName, job] of Object.entries(directGroup.jobs)) {
+        const jobIcon = job.passed ? '✅' : '❌';
+        const sp = Object.values(job.steps).filter((s) => s.passed).length;
+        const sf = Object.values(job.steps).filter((s) => !s.passed).length;
+        lines.push(`| ${jobIcon} \`${jobName}\` | ${job.conclusion ?? 'unknown'} | ${sp} | ${sf} |`);
+      }
+      lines.push('');
+    }
+
+    // ── Per-reusable-group detail ──────────────────────────────────────────
+    if (reusableEntries.length > 0) {
+      lines.push('## 📋 Per-Reusable-Workflow Detail');
+      lines.push('');
+    }
+
+    for (const [, group] of reusableEntries) {
+      const icon = this.resultIcon(group.overallResult);
+      const callerLabel = group.callerJobNames.length
+        ? ` — called via ${group.callerJobNames.map((n) => `\`${n}\``).join(', ')}`
+        : '';
+      lines.push(`### ${icon} \`${group.workflowName}\`${callerLabel}`);
+      lines.push('');
+
+      lines.push('| Job | Conclusion | Steps ✅ | Steps ❌ |');
+      lines.push('|-----|-----------|---------|---------|');
+      for (const [jobName, job] of Object.entries(group.jobs)) {
+        const jobIcon = job.passed ? '✅' : '❌';
+        // Strip the caller-job prefix from display (it's already in callerLabel)
+        const displayName = jobName.includes(' / ')
+          ? jobName.substring(jobName.lastIndexOf(' / ') + 3)
+          : jobName;
+        const stepsPassed = Object.values(job.steps).filter((s) => s.passed).length;
+        const stepsFailed = Object.values(job.steps).filter((s) => !s.passed).length;
+        lines.push(
+          `| ${jobIcon} \`${displayName}\` | ${job.conclusion ?? 'unknown'} ` +
+            `| ${stepsPassed} | ${stepsFailed} |`
+        );
+      }
+      lines.push('');
+
+      for (const [jobName, job] of Object.entries(group.jobs)) {
+        if (Object.keys(job.steps).length === 0) continue;
+        const displayName = jobName.includes(' / ')
+          ? jobName.substring(jobName.lastIndexOf(' / ') + 3)
+          : jobName;
+        lines.push(`<details><summary>Steps — <code>${displayName}</code></summary>`);
+        lines.push('');
+        lines.push('| Step | Conclusion |');
+        lines.push('|------|-----------|');
+        for (const [stepName, step] of Object.entries(job.steps)) {
+          const stepIcon = step.passed ? '✅' : '❌';
+          lines.push(`| ${stepIcon} ${stepName} | ${step.conclusion ?? 'unknown'} |`);
+        }
+        lines.push('');
+        lines.push('</details>');
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Write the grouped report to `GITHUB_STEP_SUMMARY` (if running in CI)
+   * and always print to console.
+   */
+  writeGroupedSummaryToGithub(): void {
+    const markdown = this.generateGroupedMarkdown();
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+
+    if (summaryFile) {
+      try {
+        fs.appendFileSync(summaryFile, markdown);
+        console.log(
+          '✅ Grouped reusable-workflow report written to GitHub Actions summary'
+        );
+      } catch (err) {
+        console.warn(`⚠️  Could not write to GITHUB_STEP_SUMMARY: ${err}`);
+      }
+    } else {
+      console.log(
+        '⚠️  GITHUB_STEP_SUMMARY not set — report printed to console only'
+      );
+    }
+
+    console.log('\n' + '='.repeat(80));
+    console.log(markdown);
+    console.log('='.repeat(80) + '\n');
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  private resultIcon(result: ReusableWorkflowGroup['overallResult']): string {
+    switch (result) {
+      case 'success':
+        return '✅';
+      case 'failure':
+        return '❌';
+      case 'partial_failure':
+        return '⚠️';
+      case 'skipped':
+        return '⏭️';
+      default:
+        return '❓';
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Module-level singleton helpers (mirrors the pattern in reporter.ts)
+// ---------------------------------------------------------------------------
+
+let globalReusableReporter: ReusableWorkflowReporter | null = null;
+
+/**
+ * Get (or lazily create) the module-level `ReusableWorkflowReporter` singleton.
+ * Pass `workflowName` on the first call to initialise it.
+ */
+export function getReusableReporter(
+  workflowName?: string
+): ReusableWorkflowReporter {
+  if (!globalReusableReporter) {
+    if (!workflowName) {
+      throw new Error(
+        'ReusableWorkflowReporter not initialised — call getReusableReporter(workflowName) first.'
+      );
+    }
+    globalReusableReporter = new ReusableWorkflowReporter(workflowName);
+  }
+  return globalReusableReporter;
+}
+
+/** Reset the singleton (useful between Jest test suites). */
+export function resetReusableReporter(): void {
+  globalReusableReporter = null;
+}
+
+// ---------------------------------------------------------------------------
+// Multi-workflow support
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-caller-workflow result produced by MultiWorkflowReporter.
+ * Each entry holds the run ID, the reusable-workflow groups, and a rolled-up
+ * overall result for that caller.
+ */
+export interface CallerWorkflowResult {
+  callerWorkflowName: string;
+  runId: number;
+  groups: Readonly<{ [wfName: string]: ReusableWorkflowGroup }>;
+  /** Rolled-up result across all reusable groups for this caller workflow. */
+  overallResult: 'success' | 'failure' | 'partial_failure' | 'unknown';
+}
+
+/**
+ * MultiWorkflowReporter
+ *
+ * Aggregates reports across N caller workflows in one go.
+ *
+ * Usage:
+ * ```ts
+ * const reporter = new MultiWorkflowReporter([
+ *   'Test - ci-scan',
+ *   'Test - ci-db-pr',
+ *   'Test - scan-snyk',
+ * ]);
+ * await reporter.loadAll(api);     // resolves latest run for each & groups
+ * reporter.writeToGithubSummary(); // write aggregated Markdown to CI summary
+ * const results = reporter.getResults(); // access per-workflow data in tests
+ * ```
+ */
+export class MultiWorkflowReporter {
+  private workflowNames: string[];
+  private results: { [callerName: string]: CallerWorkflowResult } = {};
+
+  constructor(workflowNames: string[]) {
+    if (workflowNames.length === 0) {
+      throw new Error('MultiWorkflowReporter requires at least one workflow name.');
+    }
+    this.workflowNames = [...workflowNames];
+  }
+
+  // -------------------------------------------------------------------------
+  // Loading
+  // -------------------------------------------------------------------------
+
+  /**
+   * For every workflow name:
+   *   1. Resolve the latest run ID via `api.getLatestRun`.
+   *   2. Create a `ReusableWorkflowReporter` instance and call `loadAndGroup`.
+   *   3. Store the groups and compute a rolled-up result.
+   *
+   * Runs sequentially to stay within GitHub API rate limits.
+   */
+  async loadAll(api: GitHubAPI): Promise<void> {
+    for (const wfName of this.workflowNames) {
+      const inner = new ReusableWorkflowReporter(wfName);
+      const runId = await api.getLatestRun(wfName);
+      await inner.loadAndGroup(api, runId);
+
+      const groups = inner.getReusableGroups();
+      this.results[wfName] = {
+        callerWorkflowName: wfName,
+        runId,
+        groups,
+        overallResult: this.computeCallerResult(groups),
+      };
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Accessors
+  // -------------------------------------------------------------------------
+
+  /** All loaded results keyed by caller workflow name. */
+  getResults(): Readonly<{ [callerName: string]: CallerWorkflowResult }> {
+    return this.results;
+  }
+
+  /** Convenience: result for a single named caller workflow. */
+  getResult(workflowName: string): CallerWorkflowResult | undefined {
+    return this.results[workflowName];
+  }
+
+  // -------------------------------------------------------------------------
+  // Built-in assertions (delegate to each caller's ReusableWorkflowReporter)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Assert that every reusable-workflow group across ALL caller workflows
+   * succeeded. Throws with a full cross-workflow summary on any failure.
+   */
+  assertAllCallerGroupsSucceed(): void {
+    const failures: string[] = [];
+    for (const [callerName, result] of Object.entries(this.results)) {
+      for (const [groupName, group] of Object.entries(result.groups)) {
+        if (group.isDirect) continue;
+        if (group.overallResult !== 'success') {
+          const failedJobs = Object.entries(group.jobs)
+            .filter(([, j]) => !j.passed)
+            .map(([n, j]) => `      job "${n}": ${j.conclusion}`)
+            .join('\n');
+          failures.push(`  [${callerName}] group "${groupName}" → ${group.overallResult}\n${failedJobs}`);
+        }
+      }
+    }
+    if (failures.length)
+      throw new Error(`Reusable groups failed across workflows:\n${failures.join('\n')}`);
+  }
+
+  /**
+   * Assert that every direct (caller-defined) job across ALL caller workflows
+   * succeeded.
+   */
+  assertAllCallerDirectJobsSucceed(): void {
+    const failures: string[] = [];
+    for (const [callerName, result] of Object.entries(this.results)) {
+      const direct = result.groups[DIRECT_JOBS_GROUP];
+      if (!direct) continue;
+      for (const [jobName, job] of Object.entries(direct.jobs)) {
+        if (!job.passed)
+          failures.push(`  [${callerName}] job "${jobName}": ${job.conclusion}`);
+      }
+    }
+    if (failures.length)
+      throw new Error(`Direct caller jobs failed:\n${failures.join('\n')}`);
+  }
+
+  /**
+   * Assert that every step across ALL caller workflows and ALL reusable groups
+   * has an acceptable conclusion (`'success'` or `'skipped'`).
+   */
+  assertAllCallerStepsAcceptable(): void {
+    const acceptable = new Set(['success', 'skipped']);
+    const failures: string[] = [];
+    for (const [callerName, result] of Object.entries(this.results)) {
+      for (const [groupName, group] of Object.entries(result.groups)) {
+        for (const [jobName, job] of Object.entries(group.jobs)) {
+          const displayJob = jobName.includes(' / ')
+            ? jobName.substring(jobName.lastIndexOf(' / ') + 3)
+            : jobName;
+          for (const [stepName, step] of Object.entries(job.steps)) {
+            if (!acceptable.has(step.conclusion ?? ''))
+              failures.push(
+                `  [${callerName}][${groupName}] ${displayJob} → "${stepName}": ${step.conclusion}`
+              );
+          }
+        }
+      }
+    }
+    if (failures.length)
+      throw new Error(`Steps with unacceptable conclusions:\n${failures.join('\n')}`);
+  }
+
+  // -------------------------------------------------------------------------
+  // Report generation
+  // -------------------------------------------------------------------------
+
+  generateMarkdown(): string {
+    const lines: string[] = [];
+
+    lines.push('# 🔄 Multi-Workflow Reusable Report');
+    lines.push('');
+    lines.push(`**Workflows included:** ${this.workflowNames.length}`);
+    lines.push('');
+
+    // ── Cross-workflow summary ──────────────────────────────────────────
+    lines.push('## 📊 Cross-Workflow Summary');
+    lines.push('');
+    lines.push(
+      '| Caller Workflow | Run ID | Overall | Reusable Groups | Jobs ✅/❌ | Steps ✅/❌ |'
+    );
+    lines.push(
+      '|-----------------|--------|---------|-----------------|-----------|------------|'
+    );
+
+    for (const [callerName, result] of Object.entries(this.results)) {
+      const icon = this.resultIcon(result.overallResult);
+      // Only list reusable groups (not the direct-jobs sentinel) in the summary
+      const reusableGroupNames = Object.keys(result.groups)
+        .filter((k) => k !== DIRECT_JOBS_GROUP)
+        .map((n) => `\`${n}\``)
+        .join(', ') || '—';
+      const { passedJobs, failedJobs, passedSteps, failedSteps } =
+        this.aggregateCounts(result.groups);
+      lines.push(
+        `| ${icon} \`${callerName}\` | ${result.runId} | ${result.overallResult} ` +
+          `| ${reusableGroupNames} ` +
+          `| ${passedJobs} / ${failedJobs} ` +
+          `| ${passedSteps} / ${failedSteps} |`
+      );
+    }
+    lines.push('');
+
+    // ── Per-caller detail ───────────────────────────────────────────────
+    lines.push('## 📋 Per-Caller Detail');
+    lines.push('');
+
+    for (const [callerName, result] of Object.entries(this.results)) {
+      const icon = this.resultIcon(result.overallResult);
+      lines.push(`### ${icon} \`${callerName}\` (run \`${result.runId}\`)`);
+      lines.push('');
+
+      const directGroup = result.groups[DIRECT_JOBS_GROUP];
+      const reusableEntries = Object.entries(result.groups).filter(
+        ([k]) => k !== DIRECT_JOBS_GROUP
+      );
+
+      // Reusable-workflow overview table for this caller
+      lines.push(
+        '| Reusable Workflow | Triggered by | Result | Jobs (✅/❌/total) | Steps (✅/❌/total) |'
+      );
+      lines.push(
+        '|-------------------|--------------|--------|-------------------|---------------------|'
+      );
+
+      for (const [, group] of reusableEntries) {
+        const gIcon = this.resultIcon(group.overallResult);
+        const callerLabel = group.callerJobNames.length
+          ? group.callerJobNames.map((n) => `\`${n}\``).join(', ')
+          : '—';
+        lines.push(
+          `| \`${group.workflowName}\` | ${callerLabel} | ${gIcon} ${group.overallResult} ` +
+            `| ${group.passedJobs} / ${group.failedJobs} / ${group.totalJobs} ` +
+            `| ${group.passedSteps} / ${group.failedSteps} / ${group.totalSteps} |`
+        );
+      }
+      lines.push('');
+
+      // Direct caller jobs summary
+      if (directGroup) {
+        const dIcon = this.resultIcon(directGroup.overallResult);
+        lines.push(
+          `> 🔧 **Direct caller jobs** (${dIcon} ${directGroup.overallResult}): ` +
+            Object.keys(directGroup.jobs).map((n) => `\`${n}\``).join(', ')
+        );
+        lines.push('');
+      }
+
+      // Per-reusable-group job breakdown with collapsible step details
+      for (const [, group] of reusableEntries) {
+        const gIcon = this.resultIcon(group.overallResult);
+        const callerLabel = group.callerJobNames.length
+          ? ` — called via ${group.callerJobNames.map((n) => `\`${n}\``).join(', ')}`
+          : '';
+        lines.push(`#### ${gIcon} \`${group.workflowName}\`${callerLabel}`);
+        lines.push('');
+        lines.push('| Job | Conclusion | Steps ✅ | Steps ❌ |');
+        lines.push('|-----|-----------|---------|---------|');
+
+        for (const [jobName, job] of Object.entries(group.jobs)) {
+          const jobIcon = job.passed ? '✅' : '❌';
+          const sp = Object.values(job.steps).filter((s) => s.passed).length;
+          const sf = Object.values(job.steps).filter((s) => !s.passed).length;
+          // Strip caller-job prefix from job name display
+          const displayName = jobName.includes(' / ')
+            ? jobName.substring(jobName.lastIndexOf(' / ') + 3)
+            : jobName;
+          lines.push(
+            `| ${jobIcon} \`${displayName}\` | ${job.conclusion ?? 'unknown'} | ${sp} | ${sf} |`
+          );
+        }
+        lines.push('');
+
+        for (const [jobName, job] of Object.entries(group.jobs)) {
+          if (Object.keys(job.steps).length === 0) continue;
+          const displayName = jobName.includes(' / ')
+            ? jobName.substring(jobName.lastIndexOf(' / ') + 3)
+            : jobName;
+          lines.push(`<details><summary>Steps — <code>${displayName}</code></summary>`);
+          lines.push('');
+          lines.push('| Step | Conclusion |');
+          lines.push('|------|-----------|');
+          for (const [stepName, step] of Object.entries(job.steps)) {
+            const sIcon = step.passed ? '✅' : '❌';
+            lines.push(`| ${sIcon} ${stepName} | ${step.conclusion ?? 'unknown'} |`);
+          }
+          lines.push('');
+          lines.push('</details>');
+          lines.push('');
+        }
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /** Write the aggregated report to `GITHUB_STEP_SUMMARY` and print to console. */
+  writeToGithubSummary(): void {
+    const markdown = this.generateMarkdown();
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+
+    if (summaryFile) {
+      try {
+        fs.appendFileSync(summaryFile, markdown);
+        console.log('✅ Multi-workflow report written to GitHub Actions summary');
+      } catch (err) {
+        console.warn(`⚠️  Could not write to GITHUB_STEP_SUMMARY: ${err}`);
+      }
+    } else {
+      console.log('⚠️  GITHUB_STEP_SUMMARY not set — printing to console only');
+    }
+
+    console.log('\n' + '='.repeat(80));
+    console.log(markdown);
+    console.log('='.repeat(80) + '\n');
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  private computeCallerResult(
+    groups: Readonly<{ [wfName: string]: ReusableWorkflowGroup }>
+  ): CallerWorkflowResult['overallResult'] {
+    const list = Object.values(groups);
+    if (list.length === 0) return 'unknown';
+    const allOk = list.every(
+      (g) => g.overallResult === 'success' || g.overallResult === 'skipped'
+    );
+    if (allOk) return 'success';
+    const allFailed = list.every((g) => g.overallResult === 'failure');
+    if (allFailed) return 'failure';
+    return 'partial_failure';
+  }
+
+  private aggregateCounts(groups: Readonly<{ [wfName: string]: ReusableWorkflowGroup }>): {
+    totalJobs: number;
+    passedJobs: number;
+    failedJobs: number;
+    totalSteps: number;
+    passedSteps: number;
+    failedSteps: number;
+  } {
+    let totalJobs = 0, passedJobs = 0, failedJobs = 0;
+    let totalSteps = 0, passedSteps = 0, failedSteps = 0;
+    for (const g of Object.values(groups)) {
+      totalJobs += g.totalJobs; passedJobs += g.passedJobs; failedJobs += g.failedJobs;
+      totalSteps += g.totalSteps; passedSteps += g.passedSteps; failedSteps += g.failedSteps;
+    }
+    return { totalJobs, passedJobs, failedJobs, totalSteps, passedSteps, failedSteps };
+  }
+
+  private resultIcon(result: 'success' | 'failure' | 'partial_failure' | 'skipped' | 'unknown'): string {
+    switch (result) {
+      case 'success': return '✅';
+      case 'failure': return '❌';
+      case 'partial_failure': return '⚠️';
+      case 'skipped': return '⏭️';
+      default: return '❓';
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Multi-workflow singleton helpers
+// ---------------------------------------------------------------------------
+
+let globalMultiReporter: MultiWorkflowReporter | null = null;
+
+/**
+ * Get (or lazily create) the module-level `MultiWorkflowReporter` singleton.
+ * Pass `workflowNames` on the first call to initialise it.
+ */
+export function getMultiWorkflowReporter(
+  workflowNames?: string[]
+): MultiWorkflowReporter {
+  if (!globalMultiReporter) {
+    if (!workflowNames) {
+      throw new Error(
+        'MultiWorkflowReporter not initialised — call getMultiWorkflowReporter(workflowNames) first.'
+      );
+    }
+    globalMultiReporter = new MultiWorkflowReporter(workflowNames);
+  }
+  return globalMultiReporter;
+}
+
+/** Reset the multi-workflow singleton (useful between Jest test suites). */
+export function resetMultiWorkflowReporter(): void {
+  globalMultiReporter = null;
+}