ai-git-tools 2.0.39 → 2.0.41

package/src/dev-modules/core/autodev-workflow.js

@@ -0,0 +1,273 @@
+/**
+ * AutoDev 工作流程編排
+ * 整合 Issue 解析 → 測試執行 → 結果發佈 → commit-all → PR
+ */
+
+import { IssueParser } from './issue-parser.js';
+import { TestDetector } from '../test/test-detector.js';
+import { createExecutor } from '../test/executor-factory.js';
+import { ResultFormatter, COMMENT_MARKER } from '../test/result-formatter.js';
+import { CodeGenerator } from '../ai/code-generator.js';
+import { GitHubAPI } from '../../pr-modules/core/github-api.js';
+import { commitAllProgrammatic } from '../../commands/commit-all.js';
+import { prProgrammatic } from '../../commands/pr.js';
+
+/**
+ * @typedef {Object} AutodevOptions
+ * @property {boolean} [dryRun]         - 乾運行：只顯示計劃，不執行
+ * @property {boolean} [verbose]        - 詳細輸出
+ * @property {string}  [framework]      - 強制指定框架（覆蓋自動偵測）
+ * @property {boolean} [skipCommit]     - 跳過 commit-all
+ * @property {boolean} [skipPr]         - 跳過 PR 建立
+ * @property {boolean} [skipAll]        - 只測試 + 發佈評論，跳過 commit 和 PR
+ * @property {boolean} [commitOnly]     - 測試 + commit，不建立 PR
+ */
+
+export class AutodevWorkflow {
+  /**
+   * @param {Object} config - .ai-git-config.js 的 autodev 區塊
+   */
+  constructor(config = {}) {
+    this.config = config;
+    this.issueParser = new IssueParser();
+    this.testDetector = new TestDetector(config.projectRoot || process.cwd());
+    this.formatter = new ResultFormatter();
+    this.codeGenerator = new CodeGenerator({
+      aiModel: config.aiModel,
+      maxRetries: config.maxRetries,
+    });
+    this.github = new GitHubAPI();
+  }
+
+  /**
+   * 主執行流程
+   * @param {string|number} issueInput
+   * @param {AutodevOptions} options
+   */
+  async execute(issueInput, options = {}) {
+    const step = (n, total, msg) =>
+      console.log(`\n[${n}/${total}] ${msg}`);
+
+    const TOTAL = this._calcTotalSteps(options);
+    let stepIdx = 0;
+
+    // ── 1. 解析 Issue ────────────────────────────────────────
+    step(++stepIdx, TOTAL, '解析 Issue...');
+    const issueData = await this._parseIssue(issueInput, options);
+
+    // ── 2. AI 自動開發（生成代碼框架）────────────────────────
+    step(++stepIdx, TOTAL, '生成代碼框架...');
+    const generatedFiles = await this._generateCode(issueData, options);
+
+    // ── 3. 偵測框架 ──────────────────────────────────────────
+    step(++stepIdx, TOTAL, '偵測測試框架...');
+    const framework = this._detectFramework(options);
+
+    // ── 4. 發現測試檔案 ──────────────────────────────────────
+    step(++stepIdx, TOTAL, '搜尋測試檔案...');
+    const testFiles = this.testDetector.discoverTests(framework, {
+      testPaths: this.config.testPaths,
+    });
+    console.log(`   找到 ${testFiles.length} 個測試檔案`);
+
+    if (options.dryRun) {
+      console.log('\n🔍 乾運行模式：以下是執行計劃\n');
+      console.log(`   Issue      : #${issueData.number} - ${issueData.title}`);
+      console.log(`   代碼檔案   : ${generatedFiles.length} 個將被建立`);
+      console.log(`   框架       : ${framework}`);
+      console.log(`   測試數量   : ${testFiles.length} 個檔案`);
+      console.log(`   Commit     : ${this._willCommit(options) ? '✅ 會執行' : '⏭️ 跳過'}`);
+      console.log(`   PR         : ${this._willCreatePR(options) ? '✅ 會執行' : '⏭️ 跳過'}`);
+      return;
+    }
+
+    if (testFiles.length === 0) {
+      console.warn('   ⚠️  未找到任何測試檔案，跳過測試步驟');
+    }
+
+    // ── 5. 執行測試 ──────────────────────────────────────────
+    step(++stepIdx, TOTAL, `執行 ${framework} 測試...`);
+    const executor = createExecutor(framework, {
+      timeout: this.config.testTimeout,
+    });
+    const testResults = await executor.run(testFiles, {
+      verbose: options.verbose,
+      projectRoot: this.config.projectRoot || process.cwd(),
+    });
+    const allPassed = testResults.failed === 0 && testResults.total > 0;
+    const passRate = testResults.total > 0
+      ? ((testResults.passed / testResults.total) * 100).toFixed(1)
+      : '-';
+    console.log(
+      `   ${allPassed ? '✅' : '❌'} ${testResults.passed}/${testResults.total} 通過（${passRate}%）· ${(testResults.duration / 1000).toFixed(1)}s`
+    );
+
+    // ── 6. 格式化結果 ─────────────────────────────────────────
+    step(++stepIdx, TOTAL, '格式化測試結果...');
+    const meta = {
+      generatedFiles: generatedFiles.length,
+    };
+    let markdown = this.formatter.formatAsMarkdown(testResults, issueData, meta);
+
+    // ── 7. 發佈到 Issue 評論（初稿，無 commit/PR 資訊）─────────
+    step(++stepIdx, TOTAL, `發佈結果到 Issue #${issueData.number}...`);
+    const commentResult = await this._postOrUpdateComment(
+      issueData,
+      markdown,
+      options
+    );
+    if (commentResult) {
+      console.log(`   📝 評論已發佈：${commentResult.url}`);
+    }
+
+    // ── 8. 若測試失敗，停止 ───────────────────────────────────
+    if (!allPassed && testResults.total > 0) {
+      console.log('\n❌ 測試未全部通過，已停止自動 commit / PR');
+      console.log('   修復失敗的測試後，重新執行 `ai autodev <issue>`');
+      return;
+    }
+
+    // 若沒有測試，給警告但繼續
+    if (testResults.total === 0) {
+      console.warn('   ⚠️  無測試可執行，繼續後續流程');
+    }
+
+    // ── 9. 自動 commit-all ───────────────────────────────────
+    if (this._willCommit(options)) {
+      step(++stepIdx, TOTAL, '自動提交（ai commit-all）...');
+      const commitResult = await commitAllProgrammatic({ verbose: options.verbose });
+      if (!commitResult.success) {
+        console.error(`   ❌ 提交失敗：${commitResult.message}`);
+        console.log('   請手動執行 `ai commit-all`，然後再次執行 `ai pr`');
+        return;
+      }
+      meta.commitHash = commitResult.commitHash;
+      console.log(`   ✅ ${commitResult.message}（${commitResult.commitHash}）`);
+    }
+
+    // ── 10. 自動建立 PR ───────────────────────────────────────
+    if (this._willCreatePR(options)) {
+      step(++stepIdx, TOTAL, '自動建立 PR（ai pr）...');
+      const prResult = await prProgrammatic({ verbose: options.verbose });
+      if (!prResult.success) {
+        console.error(`   ❌ PR 建立失敗：${prResult.message}`);
+        return;
+      }
+      meta.prUrl = prResult.prUrl;
+      console.log(`   ✅ PR 已建立：${prResult.prUrl}`);
+    }
+
+    // ── 更新 Issue 評論（加入 commit/PR 資訊）───────────────
+    if (commentResult && (meta.commitHash || meta.prUrl)) {
+      markdown = this.formatter.formatAsMarkdown(testResults, issueData, meta);
+      await this._postOrUpdateComment(issueData, markdown, options, commentResult.id);
+    }
+
+    // ── 完成摘要 ──────────────────────────────────────────────
+    console.log('\n' + '═'.repeat(60));
+    console.log('🎉 ai autodev 完成！');
+    console.log(`   Issue      : #${issueData.number} - ${issueData.title}`);
+    if (generatedFiles.length > 0) console.log(`   代碼檔案   : ${generatedFiles.length} 個已建立`);
+    console.log(`   測試       : ${testResults.passed}/${testResults.total} 通過`);
+    if (meta.commitHash) console.log(`   Commit     : ${meta.commitHash}`);
+    if (meta.prUrl)      console.log(`   PR         : ${meta.prUrl}`);
+    if (commentResult)   console.log(`   評論       : ${commentResult.url}`);
+    console.log('═'.repeat(60));
+  }
+
+  // ── 私有輔助方法 ─────────────────────────────────────────────
+
+  async _parseIssue(issueInput, options) {
+    const issueData = await this.issueParser.parse(issueInput);
+    if (options.verbose) {
+      console.log(`   #${issueData.number}: ${issueData.title}`);
+      console.log(`   倉庫: ${issueData.owner}/${issueData.repo}`);
+    }
+    return issueData;
+  }
+
+  async _generateCode(issueData, options) {
+    try {
+      const projectRoot = this.config.projectRoot || process.cwd();
+      const files = await this.codeGenerator.generateCodeFiles(issueData, projectRoot);
+
+      if (files.length === 0) {
+        console.log('   ℹ️  沒有需要生成的代碼檔案');
+        return [];
+      }
+
+      // 寫入檔案
+      const { written, skipped } = await this.codeGenerator.writeFiles(files, projectRoot);
+      console.log(`   ✅ 已寫入 ${written.length} 個檔案`);
+      if (skipped.length > 0) {
+        console.warn(`   ⚠️  跳過 ${skipped.length} 個檔案`);
+      }
+
+      if (options.verbose) {
+        written.forEach((f) => console.log(`      新建: ${f}`));
+      }
+
+      return written;
+    } catch (error) {
+      console.error(`   ❌ 代碼生成失敗：${error.message}`);
+      return [];
+    }
+  }
+
+  _detectFramework(options) {
+    const forced = options.framework || this.config.framework;
+    if (forced) {
+      console.log(`   使用指定框架：${forced}`);
+      return forced;
+    }
+    const detected = this.testDetector.detectFramework();
+    if (!detected) {
+      throw new Error(
+        '無法自動偵測測試框架\n請在 .ai-git-config.js 的 autodev.framework 指定：jest / vitest / mocha'
+      );
+    }
+    console.log(`   偵測到框架：${detected}`);
+    return detected;
+  }
+
+  async _postOrUpdateComment(issueData, markdown, options, existingCommentId = null) {
+    if (options.dryRun) return null;
+
+    try {
+      const { owner, repo, number } = issueData;
+
+      // 若有已知 ID，直接更新
+      if (existingCommentId) {
+        return this.github.editIssueComment(owner, repo, existingCommentId, markdown);
+      }
+
+      // 搜尋相同 marker 的舊評論
+      const existing = this.github.findCommentWithMarker(owner, repo, number, COMMENT_MARKER);
+      if (existing) {
+        return this.github.editIssueComment(owner, repo, existing.id, markdown);
+      }
+
+      return this.github.postCommentOnIssue(owner, repo, number, markdown);
+    } catch (error) {
+      console.error(`   ⚠️  發佈評論失敗：${error.message}`);
+      return null;
+    }
+  }
+
+  _willCommit(options) {
+    return !options.skipAll && !options.skipCommit && !options.dryRun;
+  }
+
+  _willCreatePR(options) {
+    if (options.commitOnly) return false;
+    return !options.skipAll && !options.skipPr && !options.dryRun;
+  }
+
+  _calcTotalSteps(options) {
+    // 基本步驟：Issue解析 + 代碼生成 + 框架偵測 + 測試發現 + 執行 + 格式化 + 發佈
+    let count = 7;
+    if (this._willCommit(options)) count++;
+    if (this._willCreatePR(options)) count++;
+    return count;
+  }
+}

package/src/dev-modules/core/issue-parser.js

@@ -0,0 +1,144 @@
+/**
+ * Issue 解析模組
+ * 負責解析 Issue 編號/URL，並從 GitHub API 擷取 Issue 資料
+ */
+
+import { execSync } from 'child_process';
+
+/**
+ * 標準化 IssueData 結構
+ * @typedef {Object} IssueData
+ * @property {number} number - Issue 編號
+ * @property {string} title - Issue 標題
+ * @property {string} body - Issue 說明
+ * @property {string[]} labels - 標籤列表
+ * @property {string} owner - 倉庫擁有者
+ * @property {string} repo - 倉庫名稱
+ * @property {string} url - Issue URL
+ */
+
+export class IssueParser {
+  /**
+   * 解析輸入（數字字串或完整 URL）為 Issue 編號
+   * @param {string|number} input - Issue 編號或 GitHub Issue URL
+   * @returns {number} Issue 編號
+   */
+  parseIssueNumber(input) {
+    const str = String(input).trim();
+
+    // 純數字
+    if (/^\d+$/.test(str)) {
+      return parseInt(str, 10);
+    }
+
+    // GitHub URL 格式：https://github.com/owner/repo/issues/123
+    const urlMatch = str.match(/\/issues\/(\d+)/);
+    if (urlMatch) {
+      return parseInt(urlMatch[1], 10);
+    }
+
+    throw new Error(
+      `無效的 Issue 輸入：「${input}」\n請提供 Issue 編號（如 123）或完整 URL（如 https://github.com/owner/repo/issues/123）`
+    );
+  }
+
+  /**
+   * 從 GitHub URL 解析倉庫資訊
+   * @param {string} url
+   * @returns {{ owner: string, repo: string, issueNumber: number }}
+   */
+  parseIssueURL(url) {
+    const match = url.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
+    if (!match) {
+      throw new Error(`無法解析 GitHub Issue URL：${url}`);
+    }
+    return {
+      owner: match[1],
+      repo: match[2].replace(/\.git$/, ''),
+      issueNumber: parseInt(match[3], 10),
+    };
+  }
+
+  /**
+   * 從 git remote 自動偵測 owner/repo
+   * @returns {{ owner: string, repo: string }}
+   */
+  detectRepoFromRemote() {
+    try {
+      const remoteUrl = execSync('git remote get-url origin', {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+
+      // HTTPS: https://github.com/owner/repo.git
+      const httpsMatch = remoteUrl.match(/github\.com\/([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+      if (httpsMatch) {
+        return { owner: httpsMatch[1], repo: httpsMatch[2] };
+      }
+
+      // SSH: git@github.com:owner/repo.git
+      const sshMatch = remoteUrl.match(/github\.com:([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+      if (sshMatch) {
+        return { owner: sshMatch[1], repo: sshMatch[2] };
+      }
+
+      throw new Error('無法從 git remote 解析 owner/repo');
+    } catch (error) {
+      throw new Error(`偵測 git remote 失敗：${error.message}`);
+    }
+  }
+
+  /**
+   * 透過 GitHub CLI 擷取 Issue 資料
+   * @param {string} owner
+   * @param {string} repo
+   * @param {number} issueNumber
+   * @returns {IssueData}
+   */
+  async fetchIssue(owner, repo, issueNumber) {
+    try {
+      const json = execSync(
+        `gh api repos/${owner}/${repo}/issues/${issueNumber}`,
+        { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      const data = JSON.parse(json);
+
+      return {
+        number: data.number,
+        title: data.title,
+        body: data.body || '',
+        labels: (data.labels || []).map((l) => l.name),
+        owner,
+        repo,
+        url: data.html_url,
+      };
+    } catch (error) {
+      if (error.message.includes('404')) {
+        throw new Error(
+          `Issue #${issueNumber} 不存在於 ${owner}/${repo}\n請確認 Issue 編號正確，且你有存取該倉庫的權限`
+        );
+      }
+      throw new Error(`擷取 Issue 失敗：${error.message}`);
+    }
+  }
+
+  /**
+   * 解析輸入並完整擷取 Issue 資料（主要入口）
+   * @param {string|number} input - Issue 編號或 URL
+   * @returns {Promise<IssueData>}
+   */
+  async parse(input) {
+    const str = String(input).trim();
+
+    // 如果是完整 URL，直接解析 owner/repo
+    if (str.startsWith('http')) {
+      const { owner, repo, issueNumber } = this.parseIssueURL(str);
+      return this.fetchIssue(owner, repo, issueNumber);
+    }
+
+    // 否則從 git remote 偵測
+    const issueNumber = this.parseIssueNumber(str);
+    const { owner, repo } = this.detectRepoFromRemote();
+    return this.fetchIssue(owner, repo, issueNumber);
+  }
+}

package/src/dev-modules/test/executor-base.js

@@ -0,0 +1,74 @@
+/**
+ * 測試執行器基礎類別
+ * 定義標準介面與 TestResults 結構
+ */
+
+/**
+ * @typedef {Object} TestCase
+ * @property {string} name - 測試名稱
+ * @property {string} suite - 所屬 suite（describe 區塊）
+ * @property {boolean} passed
+ * @property {number} duration - 毫秒
+ * @property {string|null} error - 失敗時的錯誤訊息
+ */
+
+/**
+ * @typedef {Object} TestResults
+ * @property {string} framework
+ * @property {number} total
+ * @property {number} passed
+ * @property {number} failed
+ * @property {number} skipped
+ * @property {number} duration - 總毫秒數
+ * @property {TestCase[]} tests
+ * @property {string|null} rawOutput
+ */
+
+export class ExecutorBase {
+  /**
+   * @param {Object} options
+   * @param {number} [options.timeout=300000] - 5 分鐘
+   */
+  constructor(options = {}) {
+    this.timeout = options.timeout ?? 300_000;
+  }
+
+  /**
+   * 執行測試（子類別實作）
+   * @param {string[]} testPaths
+   * @param {Object} options
+   * @returns {Promise<TestResults>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  async run(testPaths, options = {}) {
+    throw new Error('子類別必須實作 run() 方法');
+  }
+
+  /**
+   * 解析 JSON 輸出（子類別實作）
+   * @param {string} output
+   * @returns {TestResults}
+   */
+  // eslint-disable-next-line no-unused-vars
+  parseResults(output) {
+    throw new Error('子類別必須實作 parseResults() 方法');
+  }
+
+  /**
+   * 建立空的 TestResults 骨架
+   * @param {string} framework
+   * @returns {TestResults}
+   */
+  emptyResults(framework) {
+    return {
+      framework,
+      total: 0,
+      passed: 0,
+      failed: 0,
+      skipped: 0,
+      duration: 0,
+      tests: [],
+      rawOutput: null,
+    };
+  }
+}

package/src/dev-modules/test/executor-factory.js

@@ -0,0 +1,29 @@
+/**
+ * 測試執行器工廠
+ * 依框架名稱回傳對應的執行器實例
+ */
+
+import { JestExecutor } from './jest-executor.js';
+import { VitestExecutor } from './vitest-executor.js';
+import { MochaExecutor } from './mocha-executor.js';
+import { FRAMEWORKS } from './test-detector.js';
+
+/**
+ * @param {string} framework - 'jest' | 'vitest' | 'mocha'
+ * @param {Object} options - 傳遞給執行器的選項（如 timeout）
+ * @returns {import('./executor-base.js').ExecutorBase}
+ */
+export function createExecutor(framework, options = {}) {
+  switch (framework) {
+    case FRAMEWORKS.JEST:
+      return new JestExecutor(options);
+    case FRAMEWORKS.VITEST:
+      return new VitestExecutor(options);
+    case FRAMEWORKS.MOCHA:
+      return new MochaExecutor(options);
+    default:
+      throw new Error(
+        `不支援的測試框架：「${framework}」\n目前支援：jest、vitest、mocha\n請在 .ai-git-config.js 的 autodev.framework 指定框架`
+      );
+  }
+}

package/src/dev-modules/test/jest-executor.js

@@ -0,0 +1,86 @@
+/**
+ * Jest 測試執行器
+ * 使用 --json 取得結構化輸出
+ */
+
+import { execSync } from 'child_process';
+import { ExecutorBase } from './executor-base.js';
+
+export class JestExecutor extends ExecutorBase {
+  constructor(options = {}) {
+    super(options);
+    this.framework = 'jest';
+  }
+
+  /**
+   * 執行 Jest，回傳標準化 TestResults
+   * @param {string[]} testPaths - 若為空則執行全部
+   * @param {Object} options
+   * @param {boolean} [options.verbose]
+   * @returns {Promise<import('./executor-base.js').TestResults>}
+   */
+  async run(testPaths = [], options = {}) {
+    const pathArgs = testPaths.length > 0 ? testPaths.join(' ') : '';
+    const cmd = `npx jest --json --forceExit --passWithNoTests ${pathArgs}`;
+
+    if (options.verbose) {
+      console.log(`   執行命令：${cmd}`);
+    }
+
+    let output = '';
+    try {
+      output = execSync(cmd, {
+        encoding: 'utf-8',
+        timeout: this.timeout,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: options.projectRoot || process.cwd(),
+      });
+    } catch (error) {
+      // Jest 測試失敗時 exit code 非 0，但 stdout 仍有 JSON
+      output = error.stdout || error.output?.[1] || '';
+    }
+
+    return this.parseResults(output);
+  }
+
+  /**
+   * 將 Jest --json 輸出解析為標準 TestResults
+   * @param {string} output
+   * @returns {import('./executor-base.js').TestResults}
+   */
+  parseResults(output) {
+    const result = this.emptyResults(this.framework);
+    result.rawOutput = output;
+
+    let json;
+    try {
+      // Jest --json 可能混有非 JSON 前綴，找第一個 { 開始
+      const start = output.indexOf('{');
+      if (start === -1) return result;
+      json = JSON.parse(output.slice(start));
+    } catch (_) {
+      return result;
+    }
+
+    result.total = json.numTotalTests ?? 0;
+    result.passed = json.numPassedTests ?? 0;
+    result.failed = json.numFailedTests ?? 0;
+    result.skipped = (json.numPendingTests ?? 0) + (json.numTodoTests ?? 0);
+    result.duration = json.testResults?.reduce((acc, s) => acc + (s.perfStats?.runtime ?? 0), 0) ?? 0;
+
+    for (const suite of json.testResults ?? []) {
+      const suiteName = suite.testFilePath?.replace(process.cwd(), '').replace(/^\//, '') ?? '';
+      for (const t of suite.testResults ?? []) {
+        result.tests.push({
+          name: t.fullName ?? t.title,
+          suite: suiteName,
+          passed: t.status === 'passed',
+          duration: t.duration ?? 0,
+          error: t.failureMessages?.join('\n') || null,
+        });
+      }
+    }
+
+    return result;
+  }
+}

package/src/dev-modules/test/mocha-executor.js

@@ -0,0 +1,95 @@
+/**
+ * Mocha 測試執行器
+ * 使用 --reporter json 取得結構化輸出
+ */
+
+import { execSync } from 'child_process';
+import { ExecutorBase } from './executor-base.js';
+
+export class MochaExecutor extends ExecutorBase {
+  constructor(options = {}) {
+    super(options);
+    this.framework = 'mocha';
+  }
+
+  /**
+   * 執行 Mocha，回傳標準化 TestResults
+   * @param {string[]} testPaths
+   * @param {Object} options
+   * @returns {Promise<import('./executor-base.js').TestResults>}
+   */
+  async run(testPaths = [], options = {}) {
+    const pathArgs =
+      testPaths.length > 0 ? testPaths.map((p) => `"${p}"`).join(' ') : '"test/**/*.js" "tests/**/*.js"';
+    const cmd = `npx mocha --reporter json ${pathArgs}`;
+
+    if (options.verbose) {
+      console.log(`   執行命令：${cmd}`);
+    }
+
+    let output = '';
+    try {
+      output = execSync(cmd, {
+        encoding: 'utf-8',
+        timeout: this.timeout,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: options.projectRoot || process.cwd(),
+      });
+    } catch (error) {
+      // Mocha 失敗時 exit code 非 0，stdout 仍有 JSON
+      output = error.stdout || error.output?.[1] || '';
+    }
+
+    return this.parseResults(output);
+  }
+
+  /**
+   * 將 Mocha --reporter json 輸出解析為標準 TestResults
+   * @param {string} output
+   * @returns {import('./executor-base.js').TestResults}
+   */
+  parseResults(output) {
+    const result = this.emptyResults(this.framework);
+    result.rawOutput = output;
+
+    let json;
+    try {
+      const start = output.indexOf('{');
+      if (start === -1) return result;
+      json = JSON.parse(output.slice(start));
+    } catch (_) {
+      return result;
+    }
+
+    const stats = json.stats || {};
+    result.total = stats.tests ?? 0;
+    result.passed = stats.passes ?? 0;
+    result.failed = stats.failures ?? 0;
+    result.skipped = stats.pending ?? 0;
+    result.duration = stats.duration ?? 0;
+
+    // passes
+    for (const t of json.passes ?? []) {
+      result.tests.push({
+        name: t.fullTitle ?? t.title,
+        suite: t.fullTitle?.replace(t.title, '').trim() ?? '',
+        passed: true,
+        duration: t.duration ?? 0,
+        error: null,
+      });
+    }
+
+    // failures
+    for (const t of json.failures ?? []) {
+      result.tests.push({
+        name: t.fullTitle ?? t.title,
+        suite: t.fullTitle?.replace(t.title, '').trim() ?? '',
+        passed: false,
+        duration: t.duration ?? 0,
+        error: t.err?.message || t.err?.stack || null,
+      });
+    }
+
+    return result;
+  }
+}