差分生成と可視化：diff vs diff2html vs diff2html-cli vs git-diff

JavaScript エコシステムにおいて、コードやテキストの「差分（diff）」を扱うことは、コードレビューツール、バージョン管理システム、設定ファイルの比較など、多くの重要なシナリオで必要となります。diff、diff2html、diff2html-cli、git-diff は、この課題に取り組むための代表的なパッケージですが、それぞれが解決する問題と役割が明確に異なります。

本稿では、これらのパッケージの技術的な違い、適切な使い分け、そして実装レベルの詳細を比較します。

🏗️ 役割とアーキテクチャ：計算 vs 描画 vs CLI

まず理解すべきは、これらが「差分の計算」と「差分の描画」という異なる工程を担当している点です。

diff は、2 つのテキストやオブジェクトの間の差異を「計算」するエンジンです。

• 文字列、行、単語、配列、オブジェクトなど、さまざまな粒度で比較可能です。
• 結果は JSON 形式や Unified Diff 形式などで出力されます。
• 可視化機能は含まれていません。

// diff: 差分の計算
import * as Diff from 'diff';

const text1 = "Hello World";
const text2 = "Hello JavaScript";

const changes = Diff.diffWords(text1, text2);
// 結果：[{ value: 'Hello ' }, { value: 'World', removed: true }, { value: 'JavaScript', added: true }]

diff2html は、既存の差分データ（Unified Diff 形式など）を受け取り、HTML として「描画」します。

• diff パッケージや git diff コマンドの出力を入力として想定しています。
• 行の追加・削除を色分けし、シンタックスハイライトを適用した HTML を生成します。
• ブラウザ上での表示に最適化されています。

// diff2html: 差分の描画
import { Diff2Html } from 'diff2html';

const diffInput = `
diff --git a/file.js b/file.js
index 123..456 100644
--- a/file.js
+++ b/file.js
@@ -1 +1 @@
-console.log('old')
+console.log('new')
`;

const html = Diff2Html.html(diffInput, {
  drawFileList: true,
  matching: 'lines',
  outputFormat: 'line-by-line'
});
// 結果：HTML 文字列（テーブル形式の差分ビュー）

diff2html-cli は、diff2html の機能をターミナルから利用できるようにしたツールです。

• Node.js ライブラリとして組み込むのではなく、コマンドとして実行します。
• CI/CD でプルリクエストの差分を HTML レポートとして保存するなどに使われます。

# diff2html-cli: コマンドラインでの利用
# Git の差分をパイプして HTML ファイルを生成
 git diff | npx diff2html-cli -i stdin -o diff-report.html

git-diff は、Git の差分出力を扱うことに特化しているとされますが、npm 上の同名パッケージは維持状況に注意が必要です。

• 多くの場合、child_process で git diff を実行するラッパーか、差分文字列のパースを試みるものです。
• 機能面で diff パッケージの Unified Diff パース機能と重複することが多く、依存を増やすだけのリスクがあります。

// git-diff: 例（パッケージによる実装差異大）
// 注意：多くの git-diff パッケージは更新が停止している可能性があります
import gitDiff from 'git-diff';

// 実装はパッケージに依存しますが、基本的には git コマンドのラッパーです
// const result = await gitDiff({ cwd: './repo' }); 

🛠️ 差分の計算方法：粒度と精度

差分を「どのように」計算するかは、ユースケースによって重要です。diff パッケージはこの点で最も柔軟です。

diff は、比較の粒度を明示的に選べます。

• diffChars: 文字単位（スペルチェックなど）
• diffWords: 単語単位（文章の比較）
• diffLines: 行単位（コードの比較）
• diffJson: JSON オブジェクトの構造比較

import * as Diff from 'diff';

// 行単位での比較（コードレビュー向け）
const lineDiff = Diff.diffLines(
  "line1\nline2\nline3",
  "line1\nline2_new\nline3"
);

lineDiff.forEach(part => {
  const color = part.added ? 'green' : part.removed ? 'red' : 'grey';
  // process colored part
});

// JSON 構造の比較
const jsonDiff = Diff.diffJson(
  { a: 1, b: 2 },
  { a: 1, b: 3 }
);

diff2html は計算を行いません。

• 入力として「既に計算された差分文字列」を必要とします。
• 計算ロジックを持たないため、入力データの形式（Unified Diff など）が正確である必要があります。

// diff2html: 計算は行わず、入力された diff 文字列をレンダリングするのみ
// 誤った形式の diff 文字列を入れると正しく表示されません
const html = Diff2Html.html(validUnifiedDiffString);

git-diff は、Git のアルゴリズムに依存します。

• パッケージによっては内部で Git コマンドを呼び出すため、環境に Git がインストールされている必要があります。
• 純粋な JavaScript 環境（ブラウザなど）では動作しないことが多いです。

// git-diff: 環境依存性が高い
// ブラウザでは通常動作せず、Node.js 環境かつ Git が必要
// const diff = require('git-diff');
// diff(oldPath, newPath); // 内部で git diff コマンドを実行

🎨 可視化とカスタマイズ：HTML 生成の柔軟性

差分をユーザーに見せる際、どのように表示するかは UX に直結します。

diff2html は豊富な設定オプションを提供します。

• outputFormat: 行ごと（line-by-line）か、単語ごと（word-by-word）か。
• matching: 行のマッチングアルゴリズム（lines, words, none）。
• drawFileList: ファイル一覧を表示するかどうか。
• CSS クラスを介したスタイリングが可能ですが、CSS ファイルの別途読み込みが必要です。

// diff2html: 詳細な設定が可能
const html = Diff2Html.html(diffString, {
  drawFileList: true,
  matching: 'words',
  outputFormat: 'word-by-word',
  renderNothingWhenEmpty: false
});

// 生成された HTML には特定のクラスが付与されるため、CSS で装飾可能
// .d2h-file-wrapper, .d2h-file-header など

diff は可視化機能を持ちません。

• 自分で HTML を生成するか、diff2html などに渡す必要があります。
• 配列形式で差分が返ってくるため、独自の UI を構築する場合はこちらから始めるのが適切です。

// diff: 独自のレンダリングロジックを実装する起点
const changes = Diff.diffLines(oldText, newText);

const html = changes.map(part => {
  const className = part.added ? 'added' : part.removed ? 'removed' : 'normal';
  return `<span class="${className}">${part.value}</span>`;
}).join('');

diff2html-cli は設定をコマンドライン引数で行います。

• スクリプト内での微調整は難しいですが、CI 設定などでは便利です。

# diff2html-cli: 引数で設定を渡す
npx diff2html-cli -i stdin -o report.html --matching words --output-format word-by-word

git-diff は可視化機能を含みません。

• 出力は通常テキスト形式であり、HTML 化には追加のツールが必要です。

⚠️ 維持状況とリスク：git-diff の注意点

パッケージ選定において、維持状況（Maintenance Status）は重要な要素です。

diff と diff2html は、それぞれ分野において事実上の標準（De-facto Standard）として長く維持されています。

• diff は kpdecker によって管理され、多くの主要ライブラリで依存されています。
• diff2html は rtfpessoa によって管理され、GitHub のプルリクエスト表示などでも類似の技術が使われています。
• 定期的に更新され、セキュリティパッチや機能追加が行われています。

diff2html-cli は diff2html に追随して更新されます。

• 本体のライブラリが安定しているため、CLI ツールも信頼できます。

git-diff は注意が必要です。

• npm には同名のパッケージが複数存在し、維持されていないもの（Last publish が数年前など）が含まれています。
• 機能面でも diff パッケージの parseUnifiedDiff などで代用可能なことが多く、あえてリスクを取るメリットが薄いです。
• 新しいプロジェクトでは、diff + diff2html の組み合わせ、または Git コマンドの直接実行を推奨します。

// 推奨されないパターン（git-diff パッケージへの依存）
// import gitDiff from 'git-diff'; // 維持されていない可能性あり

// 推奨パターン（diff パッケージの利用）
import * as Diff from 'diff';
const parsed = Diff.parsePatch(gitDiffOutputString);

🌐 実装シナリオ：組み合わせて使うのが正解

実際の開発では、これらを単独で使うよりも、組み合わせて使うことがほとんどです。

シナリオ 1: Web アプリ内のコード比較機能

ユーザーが 2 つのテキストを入力し、差分を表示したい場合。

1. 計算: diff パッケージで差分を計算。
2. 変換: 計算結果を Unified Diff 形式の文字列に変換（diff が提供する機能、または自作）。
3. 描画: diff2html で HTML 生成。

import * as Diff from 'diff';
import { Diff2Html } from 'diff2html';

function compareAndRender(oldText, newText) {
  // 1. 差分計算
  const changes = Diff.diffLines(oldText, newText);
  
  // 2. Unified Diff 形式へ変換（簡易例）
  // 実際は Diff.createTwoFilesPatch などの使用を推奨
  const diffString = Diff.createTwoFilesPatch(
    'old.txt', 'new.txt', oldText, newText
  );

  // 3. HTML 描画
  return Diff2Html.html(diffString, {
    outputFormat: 'line-by-line'
  });
}

シナリオ 2: CI/CD での差分レポート

プルリクエスト作成時に、変更内容を HTML レポートとしてアーティファクトに残したい場合。

1. 取得: git diff コマンドで差分テキストを取得。
2. 変換: diff2html-cli で HTML ファイルを生成。

# CI スクリプト例
git diff origin/main...HEAD > changes.diff
npx diff2html-cli -i changes.diff -o report.html
# report.html をアーティファクトとしてアップロード

シナリオ 3: 独自の差分 UI を構築したい場合

diff2html のデザインが合わない場合。

1. 計算: diff パッケージで差分配列を取得。
2. 描画: React や Vue のコンポーネントで配列をマップして描画。

// React 例
import * as Diff from 'diff';

function DiffView({ old, new: newText }) {
  const diffs = Diff.diffLines(old, newText);

  return (
    <div className="diff-container">
      {diffs.map((part, index) => {
        const color = part.added ? '#e6ffec' : part.removed ? '#ffebe9' : 'white';
        return (
          <div key={index} style={{ backgroundColor: color }}>
            {part.value}
          </div>
        );
      })}
    </div>
  );
}

📊 比較サマリー

💡 結論：正しいツールの組み合わせ

差分処理を要件とする場合、単一の「万能パッケージ」を探すのではなく、工程ごとに最適なツールを選ぶのが賢明です。

1. 差分計算には diff を使う
   • 信頼性が高く、粒度の制御も可能です。Git の差分パースにも使えます。
2. Web 表示には diff2html を使う
   • 美しく、機能豊富な HTML 出力がすぐに得られます。CSS の読み込みを忘れないようにしてください。
3. CLI 利用には diff2html-cli を使う
   • スクリプト作成の手間を省けます。
4. git-diff パッケージは避ける
   • 維持状況のリスクと、機能の重複を避けるため、diff パッケージまたは Git コマンドの直接実行を選択してください。

この構成が、長期的なメンテナンス性と機能性のバランスにおいて最も優れています。