技術的負債スコアは下がったのに同じ場所でバグが再発するとき — スコアが見落とす結合とチャーンを計測する運用メモ

// scripts/hotspot-score.ts
// Fan-in（被参照数）× チャーン（変更頻度）でリスクのホットスポットを出す。
// 静的複雑度だけでは沈む「シンプルだがよく壊れる」ファイルを拾うのが目的。
 
import madge from "madge";
import { execSync } from "child_process";
import { writeFileSync, mkdirSync } from "fs";
 
interface Hotspot {
  file: string;
  fanIn: number;        // このファイルを参照しているモジュール数
  churn: number;        // 直近90日のコミットで変更された回数
  linesChanged: number; // 同期間の追加+削除行数
  hotspotScore: number; // fanIn × churn を対数で圧縮した合成値
}
 
// 直近90日で「何回コミットに含まれたか」をファイル単位で数える
function collectChurn(sinceDays = 90): Map<string, { commits: number; lines: number }> {
  const since = `--since=${sinceDays}.days.ago`;
  // --numstat で 追加\t削除\tパス の行が出る。バイナリは - になるので弾く。
  const raw = execSync(`git log ${since} --numstat --pretty=format:__COMMIT__`, {
    encoding: "utf8",
    maxBuffer: 64 * 1024 * 1024,
  });
 
  const churn = new Map<string, { commits: number; lines: number }>();
  const seenInCommit = new Set<string>();
 
  for (const line of raw.split("\n")) {
    if (line === "__COMMIT__") {
      seenInCommit.clear();
      continue;
    }
    const m = line.match(/^(\d+|-)\t(\d+|-)\t(.+)$/);
    if (!m) continue;
    const added = m[1] === "-" ? 0 : parseInt(m[1], 10);
    const removed = m[2] === "-" ? 0 : parseInt(m[2], 10);
    const path = m[3];
    if (!/\.(ts|tsx)$/.test(path)) continue;
 
    const cur = churn.get(path) ?? { commits: 0, lines: 0 };
    // 同一コミット内の重複カウントを避ける
    if (!seenInCommit.has(path)) {
      cur.commits += 1;
      seenInCommit.add(path);
    }
    cur.lines += added + removed;
    churn.set(path, cur);
  }
  return churn;
}
 
export async function computeHotspots(srcPath = "./src"): Promise<Hotspot[]> {
  const result = await madge(srcPath, {
    fileExtensions: ["ts", "tsx"],
    excludeRegExp: [/\.test\./, /\.spec\./, /__tests__/],
    tsConfig: "./tsconfig.json",
  });
  const graph = result.obj();
 
  // Fan-in を集計（各依存先が何回参照されているか）
  const fanIn = new Map<string, number>();
  for (const deps of Object.values(graph)) {
    for (const dep of deps) fanIn.set(dep, (fanIn.get(dep) ?? 0) + 1);
  }
 
  const churn = collectChurn(90);
 
  const hotspots: Hotspot[] = [];
  for (const [file, fi] of fanIn.entries()) {
    const c = churn.get(file);
    if (!c) continue; // 90日間触られていないなら今回のリスク対象外
    // fanIn も churn も裾が長いので対数で圧縮してから掛ける
    const score = Math.log2(fi + 1) * Math.log2(c.commits + 1);
    hotspots.push({
      file,
      fanIn: fi,
      churn: c.commits,
      linesChanged: c.lines,
      hotspotScore: Number(score.toFixed(2)),
    });
  }
 
  hotspots.sort((a, b) => b.hotspotScore - a.hotspotScore);
  mkdirSync(".architecture-analysis/scores", { recursive: true });
  writeFileSync(
    ".architecture-analysis/scores/hotspots.json",
    JSON.stringify(hotspots.slice(0, 50), null, 2)
  );
  return hotspots;
}
 
computeHotspots().then((h) => {
  console.log("上位ホットスポット:");
  for (const s of h.slice(0, 10)) {
    console.log(`  ${s.file}  fanIn=${s.fanIn} churn=${s.churn} score=${s.hotspotScore}`);
  }
});

// scripts/reconcile-score-vs-incidents.ts
// スコア上位N件が、実際のインシデント修正ファイルをどれだけ捕捉できているかを測る。
// 静的複雑度ランキングとホットスポットランキングを同じ土俵で比較する。
 
import { execSync } from "child_process";
import { readFileSync } from "fs";
 
// インシデント対応コミットが触ったファイル集合を取り出す
function incidentFiles(sinceDays = 180): Set<string> {
  const raw = execSync(
    `git log --since=${sinceDays}.days.ago --grep='incident/' -i --name-only --pretty=format:__C__`,
    { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }
  );
  const files = new Set<string>();
  for (const line of raw.split("\n")) {
    if (line === "__C__" || line.trim() === "") continue;
    if (/\.(ts|tsx)$/.test(line)) files.add(line);
  }
  return files;
}
 
// あるランキング（ファイル配列・上位が先頭）が、
// インシデント集合をどれだけ上位N件で捕捉できるかを Recall@N で返す
function recallAtN(ranking: string[], truth: Set<string>, n: number): number {
  const topN = new Set(ranking.slice(0, n));
  let hit = 0;
  for (const f of truth) if (topN.has(f)) hit++;
  return truth.size === 0 ? 0 : Number((hit / truth.size).toFixed(3));
}
 
const truth = incidentFiles(180);
 
const hotspots: { file: string }[] = JSON.parse(
  readFileSync(".architecture-analysis/scores/hotspots.json", "utf8")
);
const complexity: { filePath: string }[] = JSON.parse(
  readFileSync(".architecture-analysis/scores/debt-scores.json", "utf8")
);
 
const hotspotRanking = hotspots.map((h) => h.file);
const complexityRanking = complexity.map((c) => c.filePath);
 
for (const n of [10, 20, 30]) {
  console.log(
    `Recall@${n}  複雑度=${recallAtN(complexityRanking, truth, n)}  ` +
      `ホットスポット=${recallAtN(hotspotRanking, truth, n)}`
  );
}

# Architecture Analyst Agent（抜粋・改訂版）
 
## Prioritization Rules
- リファクタリング順位の主キーは hotspots.json の hotspotScore とする。
- 複雑度（debt-scores.json）は同点時の第2キーに留める。単独では順位を決めない。
- 提案前に reconcile レポートを読み、ホットスポット側 Recall@20 が
  複雑度側を下回っていれば、コード修正より先に計測ロジックの見直しを提案する。
- 各提案には「fanIn / churn / 直近インシデント有無」を根拠として併記する。
 
## Output
- 返済ロードマップ → .architecture-analysis/reports/refactor-roadmap.md
- 各項目に推定工数と、触った場合の依存波及ファイル一覧を添える