ai-git-tools 2.0.38 → 2.0.40

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;
+  }
+}

package/src/dev-modules/test/result-formatter.js

@@ -0,0 +1,90 @@
+/**
+ * 測試結果格式化模組
+ * 將 TestResults 轉換為 GitHub Markdown 格式，供發佈到 Issue
+ */
+
+/** 唯一識別標記，用於在多次執行時更新同一則評論 */
+export const COMMENT_MARKER = '<!-- ai-autodev-test-results -->';
+
+export class ResultFormatter {
+  /**
+   * 將 TestResults 格式化為 Markdown 字串
+   * @param {import('./executor-base.js').TestResults} results
+   * @param {import('../core/issue-parser.js').IssueData} issueData
+   * @param {Object} [meta] - 額外的 meta 資訊
+   * @returns {string}
+   */
+  formatAsMarkdown(results, issueData, meta = {}) {
+    const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    const passRate = results.total > 0
+      ? ((results.passed / results.total) * 100).toFixed(1)
+      : '0.0';
+    const allPassed = results.failed === 0 && results.total > 0;
+    const statusEmoji = allPassed ? '✅' : '❌';
+    const durationSec = (results.duration / 1000).toFixed(2);
+
+    const lines = [
+      COMMENT_MARKER,
+      '',
+      `## ${statusEmoji} 自動測試報告`,
+      '',
+      `> 由 \`ai autodev\` 自動執行 · ${now} UTC`,
+      '',
+      '### 摘要',
+      '',
+      '| 項目 | 結果 |',
+      '|------|------|',
+      `| 框架 | \`${results.framework}\` |`,
+      `| 總測試數 | ${results.total} |`,
+      `| ✅ 通過 | ${results.passed} |`,
+      `| ❌ 失敗 | ${results.failed} |`,
+      `| ⏭️ 跳過 | ${results.skipped} |`,
+      `| 通過率 | **${passRate}%** |`,
+      `| 執行時間 | ${durationSec}s |`,
+      '',
+    ];
+
+    // 失敗詳情
+    const failedTests = results.tests.filter((t) => !t.passed);
+    if (failedTests.length > 0) {
+      lines.push('### ❌ 失敗測試');
+      lines.push('');
+      for (const t of failedTests.slice(0, 20)) {
+        lines.push(`#### \`${t.name}\``);
+        if (t.suite) lines.push(`- **Suite**: ${t.suite}`);
+        if (t.error) {
+          lines.push('```');
+          lines.push(t.error.slice(0, 500));
+          lines.push('```');
+        }
+        lines.push('');
+      }
+      if (failedTests.length > 20) {
+        lines.push(`> ... 還有 ${failedTests.length - 20} 個失敗測試未顯示`);
+        lines.push('');
+      }
+    }
+
+    // 後續步驟
+    lines.push('### 下一步');
+    lines.push('');
+    if (allPassed) {
+      lines.push('- 🎉 所有測試通過！');
+      if (meta.commitHash) {
+        lines.push(`- 📦 已自動提交：\`${meta.commitHash}\``);
+      }
+      if (meta.prUrl) {
+        lines.push(`- 🔗 已自動建立 PR：${meta.prUrl}`);
+      }
+    } else {
+      lines.push('- 請修復上方列出的失敗測試');
+      lines.push('- 修復後重新執行 `ai autodev <issue>`');
+      if (results.failed > 0) {
+        lines.push(`- 或執行 \`npx ${results.framework} --watch\` 進行偵錯`);
+      }
+    }
+
+    lines.push('');
+    return lines.join('\n');
+  }
+}

package/src/dev-modules/test/test-detector.js

@@ -0,0 +1,170 @@
+/**
+ * 測試框架檢測模組
+ * 自動偵測專案使用的測試框架（Jest / Vitest / Mocha）
+ * 並發現所有相關測試檔案
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync } from 'fs';
+import { resolve, join } from 'path';
+
+/** 支援的框架識別字 */
+export const FRAMEWORKS = {
+  JEST: 'jest',
+  VITEST: 'vitest',
+  MOCHA: 'mocha',
+};
+
+export class TestDetector {
+  /**
+   * @param {string} projectRoot - 專案根目錄（預設 process.cwd()）
+   */
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+  }
+
+  /**
+   * 偵測測試框架
+   * 優先順序：設定檔 > package.json scripts > package.json devDependencies
+   * @returns {string|null} 框架名稱或 null
+   */
+  detectFramework() {
+    const root = this.projectRoot;
+
+    // 1. 專用設定檔
+    if (
+      existsSync(join(root, 'vitest.config.ts')) ||
+      existsSync(join(root, 'vitest.config.js')) ||
+      existsSync(join(root, 'vitest.config.mjs'))
+    ) {
+      return FRAMEWORKS.VITEST;
+    }
+
+    if (
+      existsSync(join(root, 'jest.config.js')) ||
+      existsSync(join(root, 'jest.config.ts')) ||
+      existsSync(join(root, 'jest.config.mjs')) ||
+      existsSync(join(root, 'jest.config.json'))
+    ) {
+      return FRAMEWORKS.JEST;
+    }
+
+    if (
+      existsSync(join(root, '.mocharc.js')) ||
+      existsSync(join(root, '.mocharc.cjs')) ||
+      existsSync(join(root, '.mocharc.json')) ||
+      existsSync(join(root, '.mocharc.yml')) ||
+      existsSync(join(root, '.mocharc.yaml'))
+    ) {
+      return FRAMEWORKS.MOCHA;
+    }
+
+    // 2. package.json
+    const pkgPath = join(root, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+        // test script
+        const testScript = pkg.scripts?.test || '';
+        if (/\bvitest\b/.test(testScript)) return FRAMEWORKS.VITEST;
+        if (/\bjest\b/.test(testScript)) return FRAMEWORKS.JEST;
+        if (/\bmocha\b/.test(testScript)) return FRAMEWORKS.MOCHA;
+
+        // devDependencies / dependencies
+        const allDeps = {
+          ...pkg.devDependencies,
+          ...pkg.dependencies,
+        };
+        if (allDeps.vitest) return FRAMEWORKS.VITEST;
+        if (allDeps.jest || allDeps['@jest/core']) return FRAMEWORKS.JEST;
+        if (allDeps.mocha) return FRAMEWORKS.MOCHA;
+      } catch (_) {
+        // 解析失敗，繼續往下
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 遞迴搜尋符合 patterns 的檔案
+   * @param {string} dir
+   * @param {RegExp[]} patterns
+   * @param {string[]} excludes - 排除目錄名稱
+   * @returns {string[]}
+   */
+  _glob(dir, patterns, excludes = ['node_modules', 'dist', '.next', 'coverage', '.git']) {
+    const results = [];
+
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch (_) {
+      return results;
+    }
+
+    for (const entry of entries) {
+      if (excludes.includes(entry)) continue;
+      const fullPath = join(dir, entry);
+      let stat;
+      try {
+        stat = statSync(fullPath);
+      } catch (_) {
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        results.push(...this._glob(fullPath, patterns, excludes));
+      } else if (patterns.some((p) => p.test(entry))) {
+        results.push(fullPath);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * 依框架發現測試檔案
+   * @param {string} framework
+   * @param {Object} [config] - 可選：{ testPaths?: string[] }
+   * @returns {string[]}
+   */
+  discoverTests(framework, config = {}) {
+    // 若使用者明確指定路徑，直接回傳（轉為絕對路徑）
+    if (config.testPaths && config.testPaths.length > 0) {
+      return config.testPaths.map((p) => resolve(this.projectRoot, p));
+    }
+
+    const commonPatterns = [
+      /\.test\.(js|ts|jsx|tsx|mjs|cjs)$/,
+      /\.spec\.(js|ts|jsx|tsx|mjs|cjs)$/,
+    ];
+
+    switch (framework) {
+      case FRAMEWORKS.JEST:
+      case FRAMEWORKS.VITEST:
+        return this._glob(this.projectRoot, commonPatterns);
+
+      case FRAMEWORKS.MOCHA: {
+        // Mocha 慣例：test/ 或 tests/ 目錄
+        const mochaPatterns = [/\.(js|ts|mjs|cjs)$/];
+        const dirs = ['test', 'tests', 'spec', 'specs'].map((d) =>
+          join(this.projectRoot, d)
+        );
+        const results = [];
+        for (const d of dirs) {
+          if (existsSync(d)) {
+            results.push(...this._glob(d, mochaPatterns));
+          }
+        }
+        // 也搜尋根目錄的 .test. / .spec. 檔案
+        results.push(...this._glob(this.projectRoot, commonPatterns));
+        return [...new Set(results)];
+      }
+
+      default:
+        // 未知框架，使用通用 patterns
+        return this._glob(this.projectRoot, commonPatterns);
+    }
+  }
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Vitest 測試執行器
+ * 使用 --reporter=json 取得結構化輸出
+ */
+
+import { execSync } from 'child_process';
+import { ExecutorBase } from './executor-base.js';
+
+export class VitestExecutor extends ExecutorBase {
+  constructor(options = {}) {
+    super(options);
+    this.framework = 'vitest';
+  }
+
+  /**
+   * 執行 Vitest，回傳標準化 TestResults
+   * @param {string[]} testPaths
+   * @param {Object} options
+   * @returns {Promise<import('./executor-base.js').TestResults>}
+   */
+  async run(testPaths = [], options = {}) {
+    const pathArgs = testPaths.length > 0 ? testPaths.join(' ') : '';
+    const cmd = `npx vitest run --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) {
+      output = error.stdout || error.output?.[1] || '';
+    }
+
+    return this.parseResults(output);
+  }
+
+  /**
+   * 將 Vitest --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;
+    }
+
+    // Vitest JSON 結構
+    const sum = (json.numPassedTests ?? 0) + (json.numFailedTests ?? 0) + (json.numPendingTests ?? 0);
+    const numTotalTests = json.numTotalTests ?? sum;
+    result.total = numTotalTests;
+    result.passed = json.numPassedTests ?? 0;
+    result.failed = json.numFailedTests ?? 0;
+    result.skipped = json.numPendingTests ?? 0;
+    result.duration = json.testResults?.reduce(
+      (acc, s) => acc + (s.perfStats?.runtime ?? s.duration ?? 0),
+      0
+    ) ?? 0;
+
+    for (const suite of json.testResults ?? []) {
+      const suiteName =
+        suite.name?.replace(process.cwd(), '').replace(/^\//, '') ?? '';
+      for (const t of suite.assertionResults ?? []) {
+        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/pr-modules/core/git-operations.js

@@ -11,9 +11,13 @@ export class GitOperations {
    */
   detectReleaseBranches() {
     try {
-      execSync('git fetch origin', { stdio: 'ignore' });
-      const branches = execSync('git branch -r')
-        .toString()
+      // 嘗試同步遠端，失敗就用本機已知的遠端資訊
+      try {
+        execSync('git fetch origin', { stdio: 'ignore', timeout: 15000 });
+      } catch (_) {
+        // fetch 失敗，繼續使用已經 cache 的遠端分支
+      }
+      const branches = execSync('git branch -r', { encoding: 'utf-8' })
         .split('\n')
         .map((b) => b.trim())
         .filter((b) => b.startsWith('origin/release-'))
@@ -31,12 +35,18 @@ export class GitOperations {
     const branches = this.detectReleaseBranches();
     if (branches.length === 0) return null;
 
+    // 優先選月分支(-m)，其次週分支(-w)，最後 fallback 到全部 release 分支
     const monthlyBranches = branches.filter((b) => b.includes('-m'));
     const weeklyBranches = branches.filter((b) => b.includes('-w'));
-    const priorityBranches = monthlyBranches.length > 0 ? monthlyBranches : weeklyBranches;
+    const priorityBranches =
+      monthlyBranches.length > 0
+        ? monthlyBranches
+        : weeklyBranches.length > 0
+          ? weeklyBranches
+          : branches;
 
     priorityBranches.sort().reverse();
-    return priorityBranches[0];
+    return priorityBranches[0] || null;
   }
 
   /**
@@ -135,9 +145,27 @@ export class GitOperations {
    */
   async push(branch) {
     try {
-      execSync(`git push -u origin ${branch}`, { stdio: 'inherit' });
+      execSync(`git push -u origin ${branch}`, {
+        stdio: ['ignore', 'inherit', 'pipe'],
+        encoding: 'utf-8',
+      });
       return true;
     } catch (error) {
+      const errMsg = (error.stderr || error.message || '').toString();
+      const is403 = errMsg.includes('403') || errMsg.includes('Write access') || errMsg.includes('write access');
+      if (is403) {
+        throw new PRError(
+          '\u63a8送失敗：git 沒有寫入權限',
+          'GIT_PUSH_FORBIDDEN',
+          [
+            '建議執行以下指令讓 git 使用 gh 的認證:',
+            '  gh auth setup-git',
+            '或者改用 SSH 權限:',
+            '  git remote set-url origin git@github.com:<org>/<repo>.git',
+          ],
+          `git push -u origin ${branch}`
+        );
+      }
       throw new PRError(
         '推送失敗',
         'GIT_PUSH_FAILED',